Tooltip

Overlay

Legenda flutuante e breve para um controle, com posicionamento via side/align do Radix e atalho de teclado opcional.

Instalação

Recebe correções por update de versão. O caminho recomendado.

npm i @trdr/ui

import { Tooltip } from "@trdr/ui/tooltip"

Uso

import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@trdr/ui/tooltip"

export function Exemplo() {
  return <Tooltip />
}

Props

TooltipPropsestende React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Root>

Prop	Tipo	Descrição
delayDuration?	number	Atraso em ms antes de abrir ao passar o mouse. Repassado ao Provider interno.

TooltipProviderPropsestende React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Provider>

TooltipTriggerPropsestende React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Trigger>

TooltipContentPropsestende React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>

Prop	Tipo	Descrição
hotkey?	React.ReactNode	Atalho de teclado, ao lado do texto. ReactNode (nao string) porque a composicao natural e com o componente `Kbd` (em construcao em paralelo nesta mesma rodada): `hotkey={<Kbd>Ctrl+K</Kbd>}`. Uma string simples tambem funciona quando nao ha Kbd disponivel.

Quando usar

Use o tooltip para explicar em uma frase curta o que um controle sem rotulo visivel faz, por exemplo um botao de icone, ou para reforcar um atalho de teclado associado a acao. Ele existe para reduzir ambiguidade de um elemento ja visivel na tela, nao para carregar informacao nova que o usuario precisa ler com calma.

Quando nao usar

Nao use tooltip para texto longo, para instrucao que o usuario precisa consultar enquanto interage (ele some assim que o mouse sai), nem para conteudo interativo (link, botao, campo): nada dentro do tooltip recebe foco. Quando o conteudo precisa ficar aberto, ter varias linhas ou algo clicavel dentro, o componente certo e o Popover ou o HoverCard, nao o Tooltip.

Anatomia

Tooltip: a raiz. Embrulha o proprio Tooltip.Provider do Radix por baixo, entao a composicao funciona sozinha, sem exigir um provider no topo da aplicacao.
TooltipProvider: exposto a parte para quem tem muitos tooltips na mesma tela e quer um unico delayDuration compartilhado. Opcional: sem ele, cada Tooltip cria o seu proprio.
TooltipTrigger (data-slot="tooltip-trigger"): o elemento que dispara a abertura ao passar o mouse ou ao focar. Use asChild para que o proprio elemento filho (um Button, por exemplo) vire o trigger, em vez de um wrapper extra.
TooltipContent (data-slot="tooltip-content"): o balao, com seta (data-slot="tooltip-arrow") apontando para o trigger. Fica dentro de um Portal, entao nunca e cortado por overflow: hidden de um container ancestral.

Posicionamento

O legado do Hub tinha oito direções fixas (top-left, bottom-right etc). Aqui isso vira duas props do Radix, mais compostas: side (top | right | bottom | left) define o lado, e align (start | center | end) define o alinhamento nesse lado. top + start e o equivalente ao antigo top-left, por exemplo.

Atalho de teclado

TooltipContent aceita hotkey, um ReactNode renderizado a direita do texto. A composicao natural e com o componente Kbd: <TooltipContent hotkey={<Kbd>Ctrl+K</Kbd>}>Buscar</TooltipContent>. Quando o Kbd nao estiver disponivel, uma string simples tambem funciona.

Acessibilidade

O TooltipContent do Radix ja carrega role="tooltip" e conecta o trigger a ele via aria-describedby automaticamente, sem trabalho manual. O tooltip abre tanto ao passar o mouse quanto ao focar o trigger por Tab, e fecha com Escape ou ao sair do foco/hover. Nenhum conteudo interativo deve entrar em TooltipContent: como ele nunca recebe foco, um link ou botao la dentro fica inalcancavel por teclado.

Slots e tokens

Todo elemento renderizado carrega um data-slot para estilizar partes internas sem depender de classe da biblioteca. Os tokens listados são extraídos do código fonte.

[data-slot="tooltip-arrow"][data-slot="tooltip-content"][data-slot="tooltip-hotkey"][data-slot="tooltip-text"][data-slot="tooltip-trigger"]

8 tokens usados

bg-popoverborder-borderfill-popoveroutline-noneshadow-mdtext-b4text-content-tertiarytext-popover-foreground