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 componente br-tooltip é a sobreposição informativa flutuante do GovBR-DS, desenvolvida para fornecer dicas breves e esclarecimentos contextuais quando o usuário foca ou posiciona o cursor sobre um elemento da interface.

Para que serve

• Esclarecimento contextual imediato: Revela descrições sucintas para botões de ícone, termos técnicos, siglas ou campos que necessitem de auxílio extra.
• Posicionamento automático: Posiciona o balão informativo em relação ao elemento de acionamento (topo, direita, baixo, esquerda) ajustando-se dinamicamente ao espaço da tela.
• Acessibilidade WAI-ARIA: Associa o acionador ao balão com role="tooltip" e aria-describedby, exibindo-se automaticamente no foco por teclado e fechando com a tecla Escape.

Quando utilizar

• Utilize quando:
  • Fornecer o rótulo descritivo de um botão que contenha apenas ícone.
  • Explicar uma sigla ou termo abreviado na interface.
• Evite e prefira outro componente quando:
  • O conteúdo for extenso, contiver botões interativos ou links navegáveis (prefira br-dropdown, br-modal ou texto inline fixo, pois tooltips desaparecem ao mover o ponteiro).
  • A informação for indispensável para a conclusão de uma tarefa crítica (ela deve estar sempre visível na tela).

Estrutura e Slots

O br-tooltip é composto por acionador e conteúdo:

• trigger: Slot obrigatório onde a aplicação declara o elemento de controle gatilho (ex.: um br-button de ícone).
• content: Slot onde é inserido o texto ou balão de conteúdo exibido pelo tooltip.

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Padrão

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

Fluxo e sobreposição

O tooltip nunca participa do fluxo da página. Quando a Popover API está disponível, seu conteúdo entra na top layer; nos demais ambientes usa position: fixed e a camada flutuante 1. A posição é aplicada antes do primeiro cálculo assíncrono para não provocar reflow.

matchTriggerWidth pode ser usado quando o conteúdo precisa acompanhar exatamente a largura do acionador. Sem essa propriedade, o tooltip preserva a largura definida pelo conteúdo e pelo mínimo visual do componente.

Tooltips externos são fechados quando um bloqueador abre. Tooltips contidos no diálogo permanecem utilizáveis e, com Popover API, são pintados acima dele pela própria plataforma.

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-cell
• br-table-header-cell

Depende de

• br-button
• br-icon

Gráfico