Tooltip

Adapter React independente em que Ark UI fornece as parts e Zag mantém hover, focus, delays, posicionamento e Escape.

Preview funcional

Executado pelo adapter independente Ark UI com comportamento Zag.

Carregando preview funcional…

Anatomia

1 Trigger — o elemento que ativa o tooltip ao passar o mouse ou focar.
2 Container do tooltip (.ds-tooltip) — fundo escuro, posicionado relativo ao trigger.
3 Seta — pseudo-elemento CSS apontando para o trigger.
4 Conteúdo — somente texto, sem elementos interativos.

Posições

O conteúdo do tooltip aparece no lado especificado do trigger. A seta (via ::before) aponta para o elemento trigger.

Com buttons de ícone

Tooltips são especialmente úteis em buttons icon-only para esclarecer sua função.

Mapeamento de tokens

Propriedade	Token	Variável CSS
fundo	`semantic.background.inverse`	`--ds-background-inverse`
texto	`semantic.brand.content.default`	`--ds-brand-content-default`
padding-x	`component.tooltip.content.padding-x.default`	`--ds-tooltip-content-padding-x-default`
padding-y	`component.tooltip.content.padding-y.default`	`--ds-tooltip-content-padding-y-default`
border-radius	`component.tooltip.content.radius.default`	`--ds-tooltip-content-radius-default`
label font-size	`component.tooltip.label.font-size.default`	`--ds-tooltip-label-font-size-default`
label line-height	`component.tooltip.label.line-height.default`	`--ds-tooltip-label-line-height-default`
label font-weight	`component.tooltip.label.font-weight.default`	`--ds-tooltip-label-font-weight-default`
arrow base	`component.tooltip.arrow.base.default`	`--ds-tooltip-arrow-base-default`
arrow depth	`component.tooltip.arrow.depth.default`	`--ds-tooltip-arrow-depth-default`
z-index	`semantic.z.tooltip`	`--ds-z-tooltip`

Quando usar

Use tooltips quando

Fornecer informação complementar e não essencial ao passar o mouse ou focar: labels de buttons de ícone, explicacoes de abreviações, esclarecimentos breves.

Não use tooltips quando

A informação é essencial (torne-a visível por padrão), o conteúdo é interativo — links, buttons ou formulários (use Popover), ou o conteúdo é longo (use Modal).

Boas práticas

Faça

Use tooltips em buttons icon-only para esclarecer sua função. Mantenha abaixo de 80 caracteres.

Click here to open settings where you can change your theme, language, and notification preferences

Não faça

Colocar conteúdo longo, links, buttons ou formulários dentro de tooltips.

Faça

Forneça informação complementar e não essencial via tooltips.

Critical information only visible on hover

Não faça

Fazer tooltips a única forma de comunicar informação crítica. Conteúdo essencial deve ser sempre visível.

Diretrizes de conteúdo

Regra	Exemplo
Abaixo de 80 caracteres	"Editar documento" — não um parágrafo inteiro
Caixa de sentença	"Copiar para área de transferência" — não "Copiar Para Área De Transferência"
Sem ponto para fragmentos	"Excluir item" — não "Excluir item."
Somente texto — sem conteúdo interativo	Sem links, buttons ou elementos de formulário dentro de tooltips

Quando escolher esta saída

Adote este adapter em projetos que escolheram Ark UI e Zag como arquitetura comportamental. Não o importe dentro da saída shadcn/Base UI.

Status: Beta
Distribuição: Adapter de source

Source do adapter

packages/react/src/ark/tooltip.jsx

import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from '@tis/react/ark/tooltip'

Interação por teclado

Tecla	Ação
`Tab` (para o trigger)	Mostra o tooltip quando o trigger recebe foco
`Escape`	Oculta o tooltip
`Tab` (saindo)	Oculta o tooltip quando o foco sai do trigger

Accessibility

Critério WCAG	Requisito	Status
1.4.13 Content on Hover/Focus (AA)	O tooltip deve ser dispensável (Escape), acessível ao mouse (pode entrar no tooltip) e persistente (permanece enquanto hover/focus ativo)	✓
4.1.2 Name, Role, Value (A)	Elemento tooltip possui `role="tooltip"`, trigger vinculado via `aria-describedby`	✓

Resumo de atributos ARIA

role="tooltip" — no elemento de conteúdo do tooltip.
aria-describedby — no trigger, apontando para o id do tooltip.
Tooltips devem aparecer tanto em hover quanto em focus, e ser dispensáveis com Escape.

Responsabilidade da saída

Preserve a semântica Ark/Zag e valide Escape, interação externa, relações ARIA e retorno de foco.

Evidência de validação

Coberta pelo Storybook da saída independente e por verificações de browser, responsividade, teclado, Axe e bundle.

Abrir referência estável