Tooltip

Beta

Una etiqueta breve que aparece al pasar el mouse o enfocar un elemento.

Abrir en Figmaregistry/ds/tooltip.tsx

import { Button } from "@/registry/ds/button";
import { Search } from "@/registry/ds/icons";
import { Tooltip, TooltipProvider } from "@/registry/ds/tooltip";

export default function TooltipBasic() {
  return (
    <TooltipProvider>
      <div className="flex flex-wrap items-center gap-6">
        <Tooltip content="Buscar materias">
          <Button variant="stroke" iconOnly={<Search />} aria-label="Buscar materias" />
        </Tooltip>
        <Tooltip side="bottom" content="Cupos limitados" description="Quedan 4 lugares en la comisión de la mañana.">
          <Button variant="tonal">Inscribirme</Button>
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}

Cuándo usarlo

Un tooltip es ayuda extra: la interfaz tiene que funcionar sin él. No existe en pantallas táctiles, así que nada esencial puede vivir ahí.

Usá Tooltip para…	Usá otra cosa para…
Nombrar un botón de solo icono.	Instrucciones necesarias → texto visible o `hint`.
Mostrar el valor completo de algo truncado.	Contenido con links o botones → Popover.
Aclarar un atajo de teclado.	Errores → `error` del campo o Alert.

Posición

Arriba por defecto. Si no entra, se voltea solo al lado opuesto.

import { Button } from "@/registry/ds/button";
import { Tooltip, TooltipProvider } from "@/registry/ds/tooltip";

export default function TooltipSides() {
  return (
    <TooltipProvider>
      <div className="flex flex-wrap items-center justify-center gap-3">
        {(["top", "right", "bottom", "left"] as const).map((side) => (
          <Tooltip key={side} side={side} content={`side="${side}"`}>
            <Button variant="stroke" size="sm">{side}</Button>
          </Tooltip>
        ))}
      </div>
    </TooltipProvider>
  );
}

Contenido

Corto: una a cinco palabras en el título. Sin punto final.
La descripción, una oración como mucho.
No repitas lo que ya dice el elemento: un botón "Guardar" no necesita un tooltip "Guardar".
Nada interactivo adentro.

Medidas

Parte	Medida
Burbuja	padding 8 × 12 · `radius-md` 8 · ancho máx. 280
Título / descripción	Text xs / Semibold · Text xs / Regular
Flecha	12 × 6
Separación del disparador	8 (6 sin flecha)
Espera	400 ms en hover · inmediato en foco

Tokens

Parte	Propiedad	Token
Burbuja y flecha	Fondo	`bg/inverse`
Título	Color	`text/inverse`
Burbuja	Sombra	`Elevation/lg`

Usa los roles inverse: oscuro en tema claro, claro en tema oscuro, sin ninguna condición.

En Figma

Propiedad en Figma	Valores	En código	Nota
Arrow	None · Top/Bottom × Left/Center/Right · Left · Right	`side · align · arrow`	En Figma se nombra dónde está la flecha; en código, de qué lado del disparador va el tooltip.
Title tooltip	Texto	`content`	—
Description	on/off + texto	`description`	—
Help icon	on/off	`—`	En código el disparador es cualquier elemento.

Instalación

npx shadcn@latest add https://polen.cdc.cool/r/tooltip.json

Playground

Configurá el componente y copiá el snippet: se genera del mismo estado que renderiza el preview.

Lado

Alineación

Retraso (ms)

ContenidoDescripciónFlecha

<Tooltip content="Cupos limitados">
  <Button variant="stroke">Inscribirme</Button>
</Tooltip>

Uso

Envolvé la app (o una zona) en TooltipProvider: al pasar de un tooltip a otro, el segundo abre sin espera.

<Tooltip content="Buscar materias">
  <Button iconOnly={<Search />} aria-label="Buscar materias" />
</Tooltip>

Props

Sobre Base UI Tooltip.

Prop	Tipo	Default	Descripción
`content`	`ReactNode`	—	Texto principal. Requerido.
`description`	`ReactNode`	—	Segunda línea opcional.
`side`	`"top" \| "right" \| "bottom" \| "left"`	"top"	Lado preferido; se voltea si no entra.
`align`	`"start" \| "center" \| "end"`	"center"	Alineación sobre ese lado.
`arrow`	`boolean`	true	Muestra la flecha.
`delay`	`number`	400	ms antes de abrir en hover.
`children`	`ReactElement`	—	Un solo elemento enfocable: el disparador.

Qué viene resuelto

Abre en hover y en foco de teclado; cierra con Esc, al salir o al perder el foco.
El mouse puede pasar del disparador a la burbuja sin que se cierre (WCAG 1.4.13).
Se reubica si no entra en pantalla.

Qué tenés que cuidar vos

El tooltip no es el nombre accesible. Un botón de solo icono necesita su aria-label igual, con el mismo texto.
El disparador tiene que ser enfocable: un botón o un link, nunca un <div> ni un icono suelto.
No pongas tooltips en elementos deshabilitados: no reciben foco ni hover. Explicá el motivo con texto visible.