Capítulo 49 de 108

Tooltip

Core Idea

Popup com informação relacionada a um elemento, exibido no hover do mouse ou foco de teclado. Built on Base UI Tooltip.

Key Concepts

  • TooltipProvider: obrigatório envolver a raiz do app (ex. app/layout.tsx) para o Tooltip funcionar corretamente; instalação via CLI já lembra desse passo.
  • side: "left" | "top" | "bottom" | "right" (físicos) ou "inline-start" | "inline-end" (lógicos, respeitam RTL).
  • Trigger em elemento desabilitado: Button disabled não dispara eventos de hover; envolver com <span className="inline-block w-fit"> como render do TooltipTrigger.

Code Examples

<Tooltip>
  <TooltipTrigger render={<span className="inline-block w-fit" />}>
    <Button variant="outline" disabled>Disabled</Button>
  </TooltipTrigger>
  <TooltipContent>
    <p>This feature is currently unavailable</p>
  </TooltipContent>
</Tooltip>
  • O que demonstra: workaround pra tooltip funcionar em botão disabled — o span recebe os eventos de pointer que o botão desabilitado ignora.
<Tooltip>
  <TooltipTrigger render={<Button variant="outline" size="icon-sm" />}>
    <SaveIcon />
  </TooltipTrigger>
  <TooltipContent>
    Save Changes <Kbd>S</Kbd>
  </TooltipContent>
</Tooltip>
  • O que demonstra: tooltip com atalho de teclado usando Kbd, padrão comum em botões de ícone.

Reference Tables

Composição:

Tooltip
├── TooltipTrigger
└── TooltipContent

Anti-patterns

  • Colocar TooltipTrigger direto num Button disabled: elementos desabilitados não disparam eventos de pointer/focus; sempre envolver com span intermediário.
  • Esquecer TooltipProvider na raiz do app: sem ele, tooltips podem não funcionar corretamente (delay compartilhado, etc).

Key Takeaways

  1. TooltipProvider no root do app é passo de instalação obrigatório, não opcional.
  2. Para tooltip em elemento desabilitado, envolver com <span> via render.
  3. side aceita valores lógicos (inline-start/inline-end) que se adaptam automaticamente a RTL.
  4. Instalação manual requer npm install @base-ui/react.
  5. Kbd (de @/components/ui/kbd) é o componente companheiro pra mostrar atalhos de teclado dentro do TooltipContent.

Connects To

  • Popover: use Popover em vez de Tooltip quando o conteúdo precisar de interação (formulário, botões clicáveis).
  • Hover Card: para preview rico ativado por hover (não apenas texto curto), prefira Hover Card.
  • Kbd: componente usado para exibir atalhos de teclado dentro do tooltip.
AnteriorPopoverPróximoHover Card