Primitiveoverlay

Tooltip

Stable

Hint transitório ancorado a um gatilho. Composto sobre Base UI Tooltip, que desenha o popup mas não o anuncia: esta camada adiciona o papel `tooltip` e liga `aria-describedby` ao gatilho enquanto ele está aberto. É a única superfície do sistema que inverte foreground e background, para separar à primeira vista um hint de um popover — onde se pode colocar o cursor.

Instalação

npx up-web-ds add tooltip

Preview

Default

Sides

Grouped

On Unavailable Action

Indisponível: o item ainda é incoming.

With Longer Text

Without Arrow

All states

Default

Sides

Grouped

On Unavailable Action

Indisponível: o item ainda é incoming.

With Longer Text

Without Arrow

Usage

Imports de Tooltip

import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from '@/components/ui/tooltip'
import { Button } from '@/components/ui/button'
import { CloseIcon } from '@/lib/up-web-icons'

Tooltip

1
2
3
4
5
6
7
8
9
10<TooltipProvider>
  <Tooltip>
    <TooltipTrigger
      render={<Button variant="ghost" size="icon" aria-label="Fechar" />}
    >
      <CloseIcon />
    </TooltipTrigger>
    <TooltipContent>Fechar</TooltipContent>
  </Tooltip>
</TooltipProvider>

Props

TooltipProvider

Props de TooltipProvider
Prop	Type	Default	Description
children	`React.ReactNode`	sem valor padrão
closeDelay	`number`	sem valor padrão	How long to wait before closing a tooltip. Specified in milliseconds.
delay	`number`	`0`	How long to wait before opening the tooltip on hover. Specified in milliseconds.
timeout	`number`	`400`	Another tooltip will open instantly if the previous tooltip is closed within this timeout. Specified in milliseconds.

Estende TooltipPrimitive.Provider.Props.

Tooltip

Props de Tooltip
Prop	Type	Default	Description
actionsRef	`React.RefObject<TooltipRootActions \| null>`	sem valor padrão	A ref to imperative actions. - `unmount`: Unmounts the tooltip popup. - `close`: Closes the tooltip imperatively when called.
children	`React.ReactNode \| PayloadChildRenderFunction<unknown>`	sem valor padrão	The content of the tooltip. This can be a regular React node or a render function that receives the `payload` of the active trigger.
defaultOpen	`boolean`	`false`	Whether the tooltip is initially open. To render a controlled tooltip, use the `open` prop instead.
defaultTriggerId	`string \| null`	sem valor padrão	ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip.
disabled	`boolean`	`false`	Whether the tooltip is disabled.
disableHoverablePopup	`boolean`	`false`	Whether the tooltip contents can be hovered without closing the tooltip.
handle	`TooltipHandle<unknown>`	sem valor padrão	A handle to associate the tooltip with a trigger. If specified, allows external triggers to control the tooltip's open state. Can be created with the Tooltip.createHandle() method.
onOpenChange	`((open: boolean, eventDetails: TooltipRoot.ChangeEventDetails) => void)`	sem valor padrão	Event handler called when the tooltip is opened or closed.
onOpenChangeComplete	`((open: boolean) => void)`	sem valor padrão	Event handler called after any animations complete when the tooltip is opened or closed.
open	`boolean`	sem valor padrão	Whether the tooltip is currently open.
trackCursorAxis	`"none" \| "both" \| "x" \| "y"`	`'none'`	Determines which axis the tooltip should track the cursor on.
triggerId	`string \| null`	sem valor padrão	ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `open` prop to create a controlled tooltip. There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set).

Estende TooltipPrimitive.Root.Props.

TooltipTrigger

Props de TooltipTrigger
Prop	Type	Default	Description
className	`string \| ((state: TooltipTriggerState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
closeDelay	`number`	`0`	How long to wait before closing the tooltip. Specified in milliseconds.
closeOnClick	`boolean`	`true`	Whether the tooltip should close when this trigger is clicked.
delay	`number`	`600`	How long to wait before opening the tooltip on hover. Specified in milliseconds.
disabled	`boolean`	`false`	If `true`, the tooltip will not open when interacting with this trigger. Note that this doesn't apply the `disabled` attribute to the trigger element. If you want to disable the trigger element itself, you can pass the `disabled` prop to the trigger element via the `render` prop.
handle	`TooltipHandle<unknown>`	sem valor padrão	A handle to associate the trigger with a tooltip.
payload	`unknown`	sem valor padrão	A payload to pass to the tooltip when it is opened.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, TooltipTriggerState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: TooltipTriggerState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende TooltipPrimitive.Trigger.Props. Aceita também os atributos padrão de um elemento React (284 não listados).

TooltipContent

Props de TooltipContent
Prop	Type	Default	Description
showArrow	`boolean`	`true`	Draws the arrow that points at the trigger. Turn it off when the tooltip sits flush against a dense surface and the pointer would only add noise.
align	`Align`	`'center'`	How to align the popup relative to the specified side.
alignOffset	`number \| OffsetFunction`	`0`	Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.
className	`string \| ((state: TooltipPopupState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, TooltipPopupState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
side	`Side`	`'top'`	Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
sideOffset	`number \| OffsetFunction`	`6`	Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.
style	`React.CSSProperties \| ((state: TooltipPopupState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende TooltipPrimitive.Popup.Props & Pick< TooltipPrimitive.Positioner.Props, 'align' | 'alignOffset' | 'side' | 'sideOffset' >. Aceita também os atributos padrão de um elemento React (275 não listados).

Composition

O TooltipProvider é o que compartilha o atraso de abertura entre tooltips vizinhos, e por isso fica acima de todos eles.

Composição de TooltipProvider

TooltipProvider

Tooltip
- TooltipTrigger
- TooltipContent

Metadata

Notas de acessibilidade

Teclado verificado por teste: o hint abre ao receber foco por Tab — não só no hover —, Escape o dispensa sem tirar o foco do gatilho (WCAG 2.2 SC 1.4.13) e sair do gatilho o fecha. Leitor de tela verificado por teste: o popup carrega role="tooltip" e o gatilho aponta aria-describedby para ele apenas enquanto está aberto, então o nome acessível continua sendo o rótulo visível do gatilho e o hint entra como descrição. Reduced motion verificado em navegador com prefers-reduced-motion: reduce — os tokens de motion colapsam para 1ms e a animação de entrada mede 0.001s, sem perder a abertura. Toque é declarado como falso por decisão de design: o conteúdo é sempre redundante em relação ao gatilho, e um gatilho desabilitado nunca o abre, então a razão de uma ação indisponível vive na página.

Classificação

Layer: Primitive
Domínio: Domain-free (compartilhado)
Categoria: overlay
Status: Stable

Origem e distribuição

Fonte: shadcn registry / tooltip
Licença: MIT
URL: https://ui.shadcn.com/r/styles/base-vega/tooltip.json
Distribuição: Interna

Acessibilidade

Teclado: revisado
Leitor de tela: revisado
Touch: não revisado
Reduced motion: revisado

Dependências

Pacotes: @base-ui/react
Ícones: Nenhum
Construído sobre: Nenhum
Usado por: Sidebar