Tooltip
Permite mostrar um texto de ajuda breve sobre um elemento ao passar o cursor sobre ele, sem exigir uma interação adicional.
- Explicar um ícone de ajuda em um formulário: esclarecer o efeito de uma opção que não é evidente pelo seu label. Ex.: "Ao ativar esta opção, o desconto se aplica mesmo a produtos que já têm preço promocional.".
- Justificar por que uma ação está desabilitada: informar o motivo específico pelo qual um controle não pode ser usado nesse momento. Ex.: "Não é possível editar esta venda porque ela tem chargebacks ativos.".
- Mostrar o valor completo de um texto truncado: revelar o conteúdo integral de uma célula ou um label que não cabe no espaço disponível. Ex.: o status completo de um pedido quando o texto é cortado com reticências em uma tabela.
- Esclarecer a ação de um ícone sem texto visível: reforçar o que um IconButton faz quando o ícone por si só pode ser ambíguo. Ex.: "Excluir".
- Mostrar ações ou conteúdo interativo: uma caixa flutuante com opções para escolher ou executar. Em vez disso, usar Popover. Ex.: um menu de "Editar", "Duplicar" e "Excluir".
- Comunicar informação indispensável para concluir uma tarefa: o Tooltip depende do cursor e não é garantido em todos os dispositivos, por isso não deve ser o único meio para algo essencial. Em vez disso, usar Alert. Ex.: uma restrição que impede salvar o formulário.
- Indicar um erro de validação de um campo específico: a mensagem deve ficar junto ao campo que a origina, visível sem depender do cursor. Em vez disso, usar o estado de erro do Input.
- Confirmar que uma ação foi executada com sucesso: avisar sobre o resultado de uma ação recém-realizada, como copiar um valor para a área de transferência. Em vez disso, usar Toast. Ex.: "Texto copiado".
Excluir
- Surface: o fundo escuro e a borda arredondada da caixa flutuante; usa o token neutral-textHigh, com uma cor de contraste inversa à do restante da interface.
- Text: a mensagem de ajuda exibida dentro da caixa, definida pela prop content.
- Arrow: indicador opcional que aponta para o disparador para reforçar o vínculo entre os dois; é ativado com arrow (oculto por padrão).
Top
Top: a caixa aparece acima do disparador. Usar quando o espaço abaixo é limitado, como na última linha de uma tabela.
Bottom
Bottom (valor padrão): a caixa aparece abaixo do disparador. É a posição mais frequente para ícones de ajuda em formulários.
Left
Left: a caixa aparece à esquerda do disparador. Usar quando o conteúdo à direita não deve cobrir outro elemento.
Right
Right: a caixa aparece à direita do disparador. É comum junto a um ícone de ajuda alinhado ao final de um label.
Sem seta
Sem seta (valor padrão): a caixa não tem indicador; é suficiente quando o disparador está próximo e o vínculo já é evidente.
Com seta
Com seta (arrow={true}): reforça o vínculo entre a caixa e o disparador. Usar quando há mais de um elemento próximo e convém deixar claro a qual ele corresponde.
O Tooltip aparece junto a um disparador específico — um ícone de ajuda, um texto truncado ou um controle desabilitado —, nunca como elemento isolado. O disparador mais frequente é um ícone de ajuda (InfoCircleIcon ou QuestionCircleIcon) ao lado do label de um campo, dentro de um formulário.
Frequência de cobrança
Indica o intervalo em dias entre cada cobrança.
Como a interação depende do cursor, em dispositivos touch ela não é garantida: quem navega só com o dedo pode não conseguir ativá-la. Por isso, a informação do Tooltip nunca deve ser a única fonte de um dado essencial para concluir a tarefa.
Preço visível
Se não tiver preço promocional, usa-se o preço original.
Reservar o Tooltip para um texto de ajuda breve e de uma única linha.
Preço visível
Se o produto não tiver um preço promocional definido no nível da variante nem no nível do kit, o sistema considera o preço original configurado na ficha do produto.
Evitar parágrafos longos ou conteúdo com várias linhas: para isso, usar Popover.
Notificações
Esclarecer a ação de um IconButton quando o ícone por si só pode ser ambíguo.
Texto copiado
Evitar usar o Tooltip para confirmar uma ação recém-executada, como "Texto copiado": para esse feedback, usar Toast.
- Interação baseada no cursor: o Tooltip é exibido ao passar o cursor sobre o disparador; não tem uma interação própria por clique ou tap. Como essa interação depende do mouse, não deve ser o único meio de comunicar informação indispensável, especialmente em dispositivos touch.
- Não abre ao focar com o teclado: diferente de outros componentes flutuantes, o Tooltip não é ativado ao percorrer a tela com Tab. Evitar depender dele como única fonte de um dado necessário para navegar pelo teclado.
- Disparador como elemento com significado próprio: quando o disparador é um ícone sem texto (IconButton, ícone de ajuda), adicionar sua própria etiqueta acessível (aria-label); o Tooltip reforça o conteúdo, não o substitui.
- Contraste da mensagem: o fundo escuro (neutral-textHigh) e o texto claro (neutral-background) já atendem ao contraste mínimo; não sobrescrever essas cores com estilos próprios.
Pontuação: com ponto final sempre, mesmo em frases curtas.
Capitalização: sentence case.
Extensão: no máximo 1-2 frases. Se o conteúdo precisar de mais desenvolvimento, usar outro componente.
Forma verbal: preferir a frase nominal quando o verbo estiver implícito no contexto. O verbo aparece só quando, sem ele, a ação não se entende. Por exemplo, ao lado de um filtro de vendas, usar "Vendas do último mês" em vez de "Mostra as vendas do último mês", porque o verbo é redundante.
Sem imperativo, sem ações nem links dentro do Tooltip.
Tom: neutro e conciso, sem linguagem de marketing.
| Disparador | Fórmula | Exemplo |
|---|---|---|
Elemento sem texto visível (icon button, ícone informativo) | Frase nominal que descreve a ação ou o elemento | "Edição de produto." |
Termo conhecido que precisa de contexto de benefício | Por que é relevante para o usuário, não sua definição | "Permite exibir seus produtos no Google grátis." |
Termo complexo ou desconhecido | O que significa, em linguagem simples | "Os campos personalizados permitem adicionar informações extras aos seus produtos." |
Restrição de plano não evidente | O que o plano exige | "Disponível no plano [nome do plano]." |
| Caso | O que fazer |
|---|---|
A informação é necessária para concluir a ação | Não usar Tooltip. Mover o conteúdo para um help text ou para a tela principal. |
O texto passa de 2 frases | Não usar Tooltip. Usar o helper text do Form Field (em contexto de formulário) ou um Alert neutro. |
O Tooltip repete o que o label do elemento já diz | Remover o Tooltip: ele não agrega informação. |
Icon button sem texto | O Tooltip é opcional, mas recomendado; o aria-label é sempre obrigatório. |
Instale o componente via terminal.
npm install @nimbus-ds/componentsimport React from "react";
import { Box, Icon, Tooltip } from "@nimbus-ds/components";
import { InfoCircleIcon } from "@nimbus-ds/icons";
const Example: React.FC = () => (
<Box display="flex" justifyContent="center">
<Tooltip content="Indica el intervalo en días entre cada cobro.">
<Icon color="neutral-textLow" source={<InfoCircleIcon />} />
</Tooltip>
</Box>
);
export default Example;As propriedades adicionais são repassadas ao elemento <Tooltip>. Consulte a documentação do elemento div para ver a lista de atributos aceitos.
- Popover — Para mostrar ações ou conteúdo com mais de uma linha, ancorado a um disparador.
- Alert — Para comunicar informação persistente que não deve depender de uma interação com o cursor.
- Icon button — Disparador frequente do Tooltip quando a ação é representada apenas por um ícone.
- Toast — Para confirmar o resultado de uma ação recém-executada, em vez de mostrá-lo em um Tooltip.
Tooltip
| Name | Type | Default | Description |
|---|---|---|---|
children* | React.ReactNode | An HTML element, or a function that returns one. It's used to set the position of the tooltip. | |
content* | string | The text that should appear in the tooltip message. | |
arrow | boolean | 'false' | Conditional for displaying the popover arrow. |
position | 'bottom' | 'bottom' | Position of the popover. |
maxWidth | string | The maxWidth property specifies the maximum width of a popover's content area. This is a responsive property and you can have the options below available for you to use. '{ "xs": "value", "md": "value", "lg": "value", "xl": "value", "xxl": "value" }' |
Ajude-nos a melhorar a documentação
Encontrou um problema ou tem uma sugestão? Conte para a gente.