Tooltip HTML/CSS

Tooltips: dicas contextuais bem feitas

Um tooltip é um pequeno elemento de UI passivo que mostra contexto extra quando o usuário passa o mouse sobre ou foca um elemento interativo. Pense nele como uma nota de rodapé presa a um botão ou ícone — útil para esclarecer um rótulo, definir um termo ou explicar o que aquele ícone minúsculo faz. Tooltips são passivos: só exibem informação e nunca contêm controles interativos. No instante em que você precisa de um link ou botão dentro, você passou do ponto e deve usar um popover ou modal.

O tooltip mais simples é o atributo nativo title: <button title="Salvar">💾</button>. Zero JS, zero CSS, suportado em todo lugar — mas não dá para estilizar, não aparece no mobile (sem hover) e é meio quebrado para usuários de teclado. Para qualquer coisa além de protótipo de dev, é preciso implementação custom.

Fundamentos de acessibilidade

Um tooltip de verdade exige role="tooltip" no balão e aria-describedby no gatilho apontando para o id do tooltip. Use describedby, não aria-label: este último substitui o nome acessível e esconderia o rótulo visível dos leitores de tela. O tooltip também precisa abrir no foco do teclado, não só no hover do mouse, ou seus campos de formulário ficam inutilizáveis com leitor de tela.

<button aria-describedby="tip1">?</button>
<span role="tooltip" id="tip1">Campo obrigatório</span>

O critério 1.4.13 da WCAG 2.1 (Content on Hover or Focus) exige três propriedades: dispensável (Esc fecha o tooltip sem mover o cursor), hoverable (o usuário consegue mover o cursor para dentro do balão sem ele sumir) e persistente (permanece até ser dispensado ou o gatilho perder foco).

Bibliotecas populares

• Tippy.js (de Atomiks) — wrapper enxuto sobre Popper, ótimos defaults, tematizável.
• Floating UI — o rebrand moderno do Popper.js, toolkit headless de posicionamento com auto-flip e detecção de colisão.
• Radix Tooltip e @headlessui/react — primitivos acessíveis presentes no shadcn/ui e no Tailwind UI.
• MUI Tooltip e Ant Design Tooltip — componentes opinativos para design systems.
• react-tooltip — drop-in simples para apps React que não precisam de um design system completo.

Posicionamento e timing

Use top como padrão e auto-flip quando o balão for cortado pelo viewport — o Floating UI cuida disso com o middleware flip(). Aplique 300–500 ms de delay de abertura para evitar piscadas quando o cursor só passa rente ao elemento; feche imediatamente para parecer responsivo. Animações devem ser sutis: fade de 120 ms e slide de 4 px. Em dispositivos touch, a estratégia é outra — não existe hover, então mapeie para long-press ou troque por popover inline.

Anti-padrões

• Informação crítica escondida em tooltip — invisível por padrão, falha no mobile, falha na WCAG.
• Parágrafos longos dentro do tooltip — use popover ou seção de ajuda inline.
• Tooltips com links ou botões — usuários não conseguem entrar neles de forma confiável; promova para popover.
• Tooltips puro CSS via :hover sem suporte a foco — inutilizáveis por teclado.

Perguntas frequentes

O atributo title basta? Só para protótipos rápidos. Não dá para estilizar, não aparece em touch e o suporte em leitores de tela é inconsistente. Em produção, use um componente real.

Quando usar popover em vez de tooltip? No momento em que o balão precisa de conteúdo interativo — links, botões, campos de formulário — troque para popover. Tooltips são read-only.

aria-describedby ou aria-label? aria-describedby. Label substitui o nome acessível; description o complementa, que é o que tooltip realmente é.

E a nova Popover API? O atributo nativo popover (Chrome 114+, Firefox 125+) é excelente para popovers, mas não é um primitivo de tooltip — ele não cuida automaticamente do wiring de aria-describedby. Combine com Floating UI ou siga com Tippy por enquanto.