Tooltip

Tooltip acrescenta uma dica curta a um controle que já tem nome. Decida antes se a dica não deveria ser texto visível — um tooltip é o lugar mais frágil para pôr qualquer coisa que a pessoa precise ler.

Exemplos

Quando usar

Use Tooltip para esclarecer brevemente um controle cujo propósito já é comunicado pelo próprio nome ou ícone.

Procure outra coisa quando:

• O texto é o nome do controle — use o label do IconButton, ou um rótulo visível.
• The content is long, or contains a link or a button — tooltips are brief, non-interactive hints. Use Dialog or inline copy.
• A informação importa no toque — ali não existe hover, e um tooltip que só abre no foco é fácil de nunca ver.

Acessibilidade

• By default, CSS draws the visible bubble from data-tip; a separate hidden <span role="tooltip"> supplies the accessible description. The open React bubble accepts pointer hits, so moving from the target onto the hint keeps it open during the existing leave grace.
• With escapeClipping={true}, a real, non-focusable <span role="tooltip"> enters the browser's top layer. It remains inside the wrapper in the DOM, preserving scoped theme, brand tokens, fonts and direction, including changes while open. It wraps long labels and clamps its bounds to the visual viewport. Both modes merge aria-describedby with your child's existing description.
• The clipping-safe mode can use another side or a shorter scrolling hint to keep its target reachable.
• tip remains a plain string: neither mode supports interactive content or moves focus into the hint.
• Abre no hover e no foco. Escape dispensa sem mover o ponteiro — é exatamente o que a WCAG 1.4.13 pede de conteúdo mostrado no hover, e o listener fica no documento, porque uma dica aberta por hover nunca tem foco dentro dela para receber a tecla.
• placement escolhe o lado (top por padrão). É uma preferência, não uma garantia: a dica vira para o lado oposto sozinha quando o escolhido seria cortado, medindo contra o visualViewport para que a barra do iOS ou o zoom de pinça não façam uma dica fora da tela parecer que cabe.
• Passe um elemento focável. Embrulhar um <span> puro produz um tooltip só de mouse, sem caminho de teclado até ele.
• No App Router do Next.js, mantenha o Tooltip e o filho dele no mesmo client component. O aria-describedby é adicionado clonando o seu elemento, e um filho que cruza a fronteira servidor/cliente chega já serializado: o atributo some do HTML do servidor, o React acusa divergência de hidratação e — como ele não corrige divergência de atributo — a descrição nunca chega ao DOM. Um 'use client' no arquivo que renderiza os dois resolve.

API e código

<span class="lyra-tooltip" data-tip="Todos no workspace conseguem abrir este link">
  <button
    class="lyra-btn lyra-btn--secondary lyra-btn--md"
    type="button"
    aria-describedby="tip-share"
  >
    Copiar link de compartilhamento
  </button>
  <span id="tip-share" role="tooltip" hidden>Todos no workspace conseguem abrir este link</span>
</span>

<lyra:tooltip tip="Deploys the current branch to production" placement="top">
    <lyra:button variant="primary" size="sm">Deploy</lyra:button>
</lyra:tooltip>