Tooltip

Dica curta ancorada num elemento. Aparece no ponteiro, no foco do teclado e no toque: uma dica que só responde ao mouse não existe para quem navega por teclado, e nunca aparece no celular, onde não há hover.

Exemplos

Lado e alinhamento são os do shadcn, e o padrão também: top-center.

Como usar

O texto vai no próprio atributo, e ele inicializa sozinho, inclusive o que chegar depois por HTMX.

<button data-tuc-tip="Gera o PDF com o layout atual">Exportar</button>
<button data-tuc-tip="..." data-placement="right-center" data-delay="600">Mais</button>
<button data-tuc-tip title="Vem do title">Do title</button>

Com data-tuc-tip vazio, o texto sai do title, que é removido: senão a dica nativa do navegador apareceria por cima da nossa. Sem o atributo, nenhum title é tocado — sequestrar todo title da página seria intrusivo demais para uma biblioteca. Sem texto nem title, não há o que mostrar, e o componente acusa erro no console.

No template do Django

<span class="tuc-badge is-warning" data-tuc-tip="Vence em {{ contract.due_date|date:'d/m/Y' }}">
  {{ contract.get_status_display }}
</span>

Num elemento que não recebe foco, como esse <span>, o componente põe tabindex="0": sem isso a dica não existiria para quem navega por teclado. Botões, links e campos já são focáveis e ficam como estão.

Em JavaScript

new Tucano.Tooltip('#export', {
  text: 'Gera o PDF',
  placement: 'right-center',
  delay: 350,         // ao apontar: evita piscar ao passar o mouse de raspão
  delayOut: 120,      // ao sair
  maxWidth: '20rem',
  className: 'tip-accent',
});

Cor

Duas variáveis, e a seta lê as mesmas: trocar a cor do balão não descola a ponta. Vale para todos, no .tuc-tip, ou num caso só, com data-tip-class.

.tip-accent { --tuc-tip-bg: var(--tuc-accent); --tuc-tip-fg: var(--tuc-accent-fg); }
.tip-danger { --tuc-tip-bg: var(--tuc-danger-fill); --tuc-tip-fg: #fff; }
.tip-light  { --tuc-tip-bg: var(--tuc-bg); --tuc-tip-fg: var(--tuc-fg); box-shadow: var(--tuc-shadow); }

<button data-tuc-tip="Só administradores podem excluir" data-tip-class="tip-danger">Excluir</button>

Quando aparece e quando some

Só uma dica fica aberta por vez: abrir outra fecha a anterior.

Acessibilidade

O balão é um role="tooltip", e o elemento aponta para ele com aria-describedby: o leitor de tela lê a dica junto com o botão, como descrição dele, e não como um elemento perdido na página.

A dica é só texto e não recebe ponteiro. Link, botão ou informação de que a pessoa precisa para concluir a tarefa não cabem nela: quem não aponta nem foca aquele elemento nunca vai ver. A seta é desenho e leva aria-hidden. Com prefers-reduced-motion a dica aparece e some sem animação.

API

Gerada do código a cada build — se algo não está aqui, não existe.

Opções