Tooltip

O mk-tooltip envolve um elemento filho em um trigger e exibe um balão de texto ao passar o mouse ou ao focar via teclado. Ele ajuda a desambiguar ícones sem rótulo, explicar termos técnicos, descrever o efeito de uma ação ou mostrar o texto completo de um conteúdo truncado — aparecendo próximo ao elemento de referência com uma seta indicadora. O conteúdo é limitado a 60 caracteres para evitar transbordamento.

Quando usar

Use o tooltip para complementar informações que o espaço da interface não comporta, sem interromper o fluxo do usuário.

Use quando:

Um ícone não tem rótulo visível e precisa de descrição.
Um termo precisa de explicação rápida sem abrir outro componente.
Um conteúdo truncado precisa exibir o valor completo ao passar o cursor.

Prefira uma alternativa quando:

A informação for essencial para o uso da feature — coloque no próprio layout, não no tooltip.
O conteúdo for longo ou exigir formatação rica — use um popover.
O dispositivo for touch — tooltips de hover não funcionam em telas touch.

Anatomia

#	Parte	Obrigatório?	Função
1	Balão de texto	Sim	Conteúdo da dica. Fundo escuro com texto branco por padrão.
2	Seta indicadora	Sim	Aponta para o elemento de referência, ancorando visualmente o tooltip.

Padrão

import { MkTooltip, MkButton } from '@db1/makuco-ui-react';

<MkTooltip content="Texto de ajuda contextual">
  <MkButton>Passe o mouse</MkButton>
</MkTooltip>

<mk-tooltip content="Texto de ajuda contextual">
  <mk-button>Passe o mouse</mk-button>
</mk-tooltip>

Posicionamento

Escolha a combinação de posicionamento que mantenha o tooltip dentro da área visível da tela e mais próximo do elemento de referência. O tooltip suporta 8 posições relativas ao elemento trigger.

<MkTooltip content="Acima à esquerda" placement="top-left">
  <MkButton>top-left</MkButton>
</MkTooltip>

<MkTooltip content="Abaixo ao centro" placement="bottom-center">
  <MkButton>bottom-center</MkButton>
</MkTooltip>

<MkTooltip content="À direita" placement="right">
  <MkButton>right</MkButton>
</MkTooltip>

<mk-tooltip content="Acima à esquerda" placement="top-left">
  <mk-button>top-left</mk-button>
</mk-tooltip>

<mk-tooltip content="Abaixo ao centro" placement="bottom-center">
  <mk-button>bottom-center</mk-button>
</mk-tooltip>

<mk-tooltip content="À direita" placement="right">
  <mk-button>right</mk-button>
</mk-tooltip>

Comportamento

O tooltip aparece após um breve atraso ao passar o cursor sobre o elemento acionador (geralmente 300–500ms) e desaparece ao mover o cursor para fora. O atraso evita flashes indesejados ao mover rapidamente pela tela.

O tooltip também é ativado por foco via teclado — ao navegar com Tab até o elemento acionador, o balão é exibido da mesma forma que ao passar o cursor.

Props

Prop	Tipo	Padrão	Descrição
`content`	`string`	`""`	Texto exibido no balão. Máximo de 60 caracteres.
`placement`	`"top-left" \| "top-center" \| "top-right" \| "right" \| "left" \| "bottom-left" \| "bottom-center" \| "bottom-right"`	`"top-center"`	Posição do balão relativa ao trigger.

Slots

Slot	Descrição
(default)	Elemento que serve como trigger do tooltip.

Acessibilidade

O balão é renderizado via portal no body com role="tooltip".
O trigger recebe aria-describedby apontando para o id do balão.
O tooltip é ativado por foco (focusin/focusout) além de mouse — acessível por teclado.
O conteúdo é limitado a 60 caracteres para garantir que o balão não transborde em viewports pequenas.

Informação obrigatória: Não use tooltip para informação essencial à execução de uma ação — tooltips são invisíveis por padrão e usuários de teclado ou touch podem nunca vê-los. Se a informação for necessária, ela deve estar sempre visível no layout.

Fechar com Escape: Se o tooltip abrir por foco de teclado, pressionar Escape deve fechá-lo, permitindo que o usuário dispense a dica sem mover o foco.

Tooltip

On this page