Tooltip

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

O br-tooltip exibe uma dica rápida e contextual quando o usuário foca ou passa o mouse sobre um elemento.

Coloque o texto da dica em text ou no slot padrão, e vincule-o ao elemento acionador através de target ou colocando o acionador no slot trigger.

<br-button id="btn-ajuda" shape="circle" aria-label="Ajuda">?</br-button>
<br-tooltip target="#btn-ajuda" text="Clique para obter informações"></br-tooltip>

Quando usar

• Esclarecer o significado de botões que usam apenas ícones ou rótulos abreviados.

Quando evitar

• Informações essenciais que todos os usuários precisam ler imediatamente: exiba como texto visível na página.
• Conteúdos longos com links clicáveis: use br-message ou diálogo.

Consulte as diretrizes de design do GovBR.

Exemplo(s)

Exemplos

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

Sobreposição e posicionamento

O tooltip flutua sobre a página sem empurrar os elementos ao redor. Em navegadores compatíveis, utiliza a Popover API na top layer, evitando que o conteúdo seja cortado por elementos com overflow: hidden.

• Largura: por padrão, a largura adapta-se ao texto da dica. Defina match-trigger-width para que acompanhe a largura do elemento acionador.
• Interação com modais: tooltips externos são fechados automaticamente quando uma tela bloqueadora (como modal ou scrim) se abre.

Propriedades

ariaLabel

Atributo	aria-label
Descrição	Nome acessível do popover. Quando omitido, usa o rótulo derivado do estado visual.
Tipo	string
Valor padrão	null

customId

Atributo	custom-id
Descrição	Identificador único do componente. Quando omitido, um valor é gerado automaticamente. > Padrão: valor único gerado por generateUniqueId().
Tipo	string
Valor padrão	generateUniqueId()

density

Atributo	density
Descrição	Define a densidade visual do componente. - small: Alta densidade (componente menor, mais compacto e com menos espaçamento). - medium: Densidade intermediária, padrão recomendado para a maioria dos casos. - large: Baixa densidade (componente maior, mais espaçamento e altura). Valores inválidos usam medium.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

hideDelay

Atributo	hide-delay
Descrição	Atraso em milissegundos antes de ocultar. Valores negativos usam 0.
Tipo	number
Valor padrão	null

interaction

Atributo	interaction
Descrição	Modo de interação para exibição do tooltip: 'hover' ou 'click'. Valores inválidos usam hover.
Tipo	"click" | "hover"
Valor padrão	'hover'

isAutoVisible

Atributo	is-auto-visible
Descrição	Exibe automaticamente sem interação quando true; caso contrário, depende do acionador.
Tipo	boolean
Valor padrão	false

matchTriggerWidth

Atributo	match-trigger-width
Descrição	Faz o conteúdo acompanhar a largura do acionador enquanto estiver visível. O valor padrão false preserva a largura determinada pelo conteúdo.
Tipo	boolean
Valor padrão	false

position

Atributo	position
Descrição	Posição do tooltip em relação ao acionador. Valores inválidos usam top.
Tipo	"bottom" | "left" | "right" | "top"
Valor padrão	'top'

showDelay

Atributo	show-delay
Descrição	Atraso em milissegundos antes de exibir. Valores negativos usam 0.
Tipo	number
Valor padrão	null

state

Atributo	state
Descrição	Estado visual do tooltip: 'info', 'warning', 'error', 'danger' ou 'success'. Valores inválidos usam info.
Tipo	"danger" | "error" | "info" | "success" | "warning"
Valor padrão	'info'

type

Atributo	type
Descrição	Tipo do tooltip: 'standard' (simples) ou 'popover' (mais rico, com fechamento por interação). Valores inválidos usam standard.
Tipo	"popover" | "standard"
Valor padrão	'standard'

Slots

Nome	Descrição
"content"	Slot para o conteúdo exibido no tooltip.
"trigger"	Slot para o elemento que aciona a exibição do tooltip.

Eventos

Evento	Descrição	Depreciação	Propagação
brDidClose	Emitido quando o tooltip fecha.	---	true
brDidOpen	Emitido quando o tooltip abre.	---	true

Métodos

hide

Descrição	Oculta o tooltip programaticamente (alias para hideTooltip).
Assinatura	hide() => Promise<void>
Parâmetros	---

hideTooltip

Descrição	Oculta o tooltip programaticamente.
Assinatura	hideTooltip() => Promise<void>
Parâmetros	---

setTriggerElement

Descrição	Define um trigger externo para o tooltip.
Assinatura	setTriggerElement(element: HTMLElement | null) => Promise<void>
Parâmetros	element:

show

Descrição	Exibe o tooltip programaticamente (alias para showTooltip).
Assinatura	show() => Promise<void>
Parâmetros	---

showTooltip

Descrição	Exibe o tooltip programaticamente.
Assinatura	showTooltip() => Promise<void>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"arrow"	Seta indicativa do tooltip.
"container"	Wrapper principal do tooltip.
"content"	Área de conteúdo do tooltip.
"trigger"	Área do acionador do tooltip.

Acessibilidade

O balão tem role="tooltip" (ou role="dialog" quando type="popover") e é associado ao acionador por aria-describedby e aria-controls. O acionador mais o balão compartilham o mesmo id base.

Teclado e foco

• O tooltip aparece quando o acionador recebe foco por teclado (focusin) e some no focusout, além do hover.
• Escape fecha o balão e devolve o foco ao acionador.
• Se o elemento no slot trigger já é focável, ele mantém o foco; se não for, o wrapper do acionador recebe tabindex="0" para ser alcançável por teclado.
• No modo type="popover", o foco é movido para dentro do conteúdo ao abrir, já que ele pode conter controles interativos.

Uso

• interaction="hover" (padrão) x interaction="click": em telas de toque e para conteúdo que precisa ser lido com calma, prefira click.
• Conteúdo essencial não deve viver só no tooltip — ele pode ser dispensado e não fica visível o tempo todo.
• Para acionadores só com ícone, defina aria-label no br-tooltip.

Movimento

Aparição e desaparecimento respeitam prefers-reduced-motion: reduce; show-delay/hide-delay controlam o tempo de exibição.

Dependências

Usado por

• br-table-action
• br-table-bar
• br-table-cell
• br-table-header-cell

Depende de

• br-button
• br-icon

Gráfico