Tooltip

Componentes/Overlay e disclosure

ImplementaçãoHTML/CSS/JSArk/ZagReact · shadcn/Base UIAngular

Exibe um label visual breve quando um trigger recebe hover ou focus.

DesignUsoImplementaçãoAcessibilidade

Seção da documentaçãoDesignUsoImplementaçãoAcessibilidade

Design

Preview funcional

Executado pelo runtime JavaScript estável ds-tis/tooltip.

Carregando preview funcional…

Abrir playground HTML/CSS/JS

Anatomia

1 Edit document 2 3 4

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.

Top Tooltip on top

Bottom Tooltip on bottom

Left Tooltip on left

Right Tooltip on right

Com buttons de ícone

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

Edit

Delete

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

Uso

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

Settings

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.

Edit document

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

Implementação

Status

Estável

Distribuição

Pacote npm

Instalação

npm

npm install ds-tis

pnpm

pnpm add ds-tis

yarn

yarn add ds-tis

bun

bun add ds-tis

Importações

import 'ds-tis/css'
import { initTooltips } from 'ds-tis/tooltip'

initTooltips()

Markup

<div class="ds-tooltip ds-tooltip--top">
  <button type="button" aria-label="Editar projeto" aria-describedby="edit-tooltip">Editar</button>
  <span class="ds-tooltip__content" id="edit-tooltip" role="tooltip">Editar projeto</span>
</div>

Contrato da implementação Web

Classes CSS

Classe	Descrição
ds-tooltip	Wrapper ao redor do trigger e conteúdo do tooltip
ds-tooltip__content	O elemento label do tooltip (com seta via ::before)
ds-tooltip--top	Posiciona o tooltip acima do trigger
ds-tooltip--right	Posiciona o tooltip à direita
ds-tooltip--bottom	Posiciona o tooltip abaixo do trigger
ds-tooltip--left	Posiciona o tooltip à esquerda

Acessibilidade

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

Inicialize o runtime público após o render e destrua-o quando a view responsável for desmontada.

Evidência de validação

Coberta pelo Storybook estável, testes do runtime público quando aplicável, cenários de teclado, responsividade e Axe.

Abrir referência estável