Tooltip

Rótulo curto que explica um controle ao passar o mouse ou focar.

O Tooltip nomeia ou explica um controle em uma frase, como um botão só de ícone. Ele não guarda ação nem conteúdo longo: para isso use Popover ou Modal.

import { Tooltip } from "@rastreio-x/ui";

Padrão

O gatilho e o Tooltip.Content ficam lado a lado dentro de Tooltip. O gatilho precisa ser focável, como um botão.

Posição

placement aceita top (padrão), right, bottom e left; o tooltip se reposiciona se faltar espaço.

Com seta

showArrow com Tooltip.Arrow aponta para o gatilho.

Gatilho próprio

Use Tooltip.Trigger para envolver um elemento que não é botão. Garanta que ele receba foco.

Atrasado

No Admin

Ao lado de um indicador, um botão de ajuda explica como o valor é calculado. O atraso de 200 ms evita que o tooltip abra ao passar o mouse rápido.

Entregas no Prazo

Anatomia

Tooltip
├── Tooltip.Arrow
├── Tooltip.Content
└── Tooltip.Trigger

Tooltip.Trigger: o elemento que abre o tooltip.
Tooltip.Content: o balão de texto.
Tooltip.Arrow: a seta opcional.

Propriedades

Raiz (Tooltip):

Tooltip
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`closeDelay`	`number`	`500`	Atraso em milissegundos antes de fechar.
`defaultOpen`	`boolean`	-	Abre o elemento na primeira renderização (não controlado).
`delay`	`number`	`1500`	Atraso em milissegundos antes de agir.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isOpen`	`boolean`	-	Controla se o elemento está aberto (controlado).
`onOpenChange`	`((isOpen: boolean) => void)`	-	Chamada quando o elemento abre ou fecha.
`shouldCloseOnPress`	`boolean`	`true`	Fecha o tooltip ao pressionar o gatilho.
`shouldSkipAnimation`	`boolean`	`false`	Mostra e esconde sem animação de entrada ou saída.
`trigger`	`'focus' \| 'hover'`	`'hover'`	Nome do componente que abriu a camada (exposto em `data-trigger`).

Conteúdo (Tooltip.Content):

Tooltip.Content
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`arrowBoundaryOffset`	`number`	`0`	Distância mínima entre a borda da seta e a borda da camada.
`className`	`ClassNameOrFunction<TooltipRenderProps>`	`'react-aria-Tooltip'`	Classes CSS aplicadas ao elemento.
`containerPadding`	`number`	`12`	Espaço mínimo entre a camada e a borda do contêiner.
`crossOffset`	`number`	`0`	Deslocamento adicional no eixo transversal entre a camada e o âncora.
`defaultOpen`	`boolean`	-	Abre o elemento na primeira renderização (não controlado).
`isEntering`	`boolean`	-	Indica que a animação de entrada está em andamento.
`isExiting`	`boolean`	-	Indica que a animação de saída está em andamento.
`isOpen`	`boolean`	-	Controla se o elemento está aberto (controlado).
`offset`	`number`	`0`	Deslocamento adicional no eixo principal entre a camada e o âncora.
`onOpenChange`	`((isOpen: boolean) => void)`	-	Chamada quando o elemento abre ou fecha.
`placement`	`Placement`	`'top'`	Lado em que o tooltip abre em relação ao gatilho (padrão `top`).
`render`	`DOMRenderFunction<'div', TooltipRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`shouldFlip`	`boolean`	`true`	Inverte o lado quando não há espaço suficiente.
`showArrow`	`boolean`	-	Mostra a seta apontando para o gatilho.
`style`	`StyleOrFunction<TooltipRenderProps>`	-	Estilos em linha aplicados ao elemento.
`triggerRef`	`RefObject<Element \| null>`	-	Referência ao elemento a que a camada se posiciona.
`UNSTABLE_portalContainer`	`Element`	`document.body`	Elemento que recebe o portal da camada. Interface instável.

O balão entra e sai com opacity e transform em transição curta. Ao mover o mouse de um tooltip para outro, a animação é pulada (shouldSkipAnimation). Com prefers-reduced-motion, a transição é reduzida a 0,01 ms.

Acessibilidade

Abre por hover e por foco do teclado; Esc fecha.
O texto é ligado ao gatilho por aria-describedby; um botão só de ícone ainda precisa de aria-label.
Não coloque ação, link nem conteúdo essencial no tooltip: ele não aparece em telas de toque.
Mantenha a frase curta, sem pontuação final quando for um rótulo.

Boas práticas

Faça

Uma frase curta que acrescenta algo: Como é calculado.

Evite

Repetir o rótulo do botão, ou esconder no tooltip uma informação necessária para decidir.

Use em botões só de ícone e em indicadores que pedem explicação.
Texto sem links nem botões; para conteúdo interativo use Popover.
Em desktop, ajuste delay para 200 ms ou mais em listas densas.
O que a pessoa precisa saber para agir fica visível, não no tooltip.

Relacionados

Button para o gatilho mais comum.
Modal para conteúdo longo ou interativo.
Chip como gatilho de explicação de estado.