Tooltip

Pista corta anclada a un elemento. Aparece con el puntero, con el foco del teclado y al tocar: una pista que solo responde al ratón no existe para quien navega con teclado, y nunca aparece en el móvil, donde no hay hover.

Multa e intereses

Ejemplos

Lado y alineación son los de shadcn, y el valor predeterminado también: top-center.

Lados

top, right, bottom y left. Si no cabe, pasa al lado opuesto y la flecha acompaña.

Alineación

start, center y end en el eje del lado. La flecha apunta siempre al centro del disparador.

Texto largo

Hace salto de línea a 16rem de ancho; maxWidth lo cambia en JS.

Retardo

data-delay="900" espera más antes de aparecer con el puntero. Con el foco, aparece al instante.

Cómo usar

El texto va en el propio atributo, y se inicializa solo, incluso lo que llegue después por HTMX.

<button data-tuc-tip="Genera el PDF con el diseño actual">Exportar</button>
<button data-tuc-tip="..." data-placement="right-center" data-delay="600">Más</button>
<button data-tuc-tip title="Viene del title">Del title</button>

Atributo	Predeterminado	Para qué
`data-tuc-tip`	—	El texto de la pista. Vacío, usa el `title`
`data-placement`	`top-center`	Lado y alineación
`data-delay`	`350`	Espera, en ms, antes de aparecer con el puntero
`data-tip-class`	—	Clase extra en el globo, para cambiar el color en un solo caso

Con data-tuc-tip vacío, el texto sale del title, que se quita: si no, la pista nativa del navegador aparecería encima de la nuestra. Sin el atributo, ningún title se toca — secuestrar todos los title de la página sería demasiado intrusivo para una biblioteca. Sin texto ni title, no hay nada que mostrar, y el componente registra un error en la consola.

En la plantilla de Django

<span class="tuc-badge is-warning" data-tuc-tip="Vence el {{ contract.due_date|date:'d/m/Y' }}">
  {{ contract.get_status_display }}
</span>

En un elemento que no recibe foco, como ese <span>, el componente pone tabindex="0": sin eso la pista no existiría para quien navega con teclado. Botones, enlaces y campos ya son enfocables y se quedan como están.

En JavaScript

new Tucano.Tooltip('#export', {
  text: 'Genera el PDF',
  placement: 'right-center',
  delay: 350,         // al apuntar: evita parpadeos al pasar el ratón de refilón
  delayOut: 120,      // al salir
  maxWidth: '20rem',
  className: 'tip-accent',
});

Color

Dos variables, y la flecha lee las mismas: cambiar el color del globo no despega la punta. Vale para todos, en .tuc-tip, o para un solo caso, con data-tip-class.

.tip-accent { --tuc-tip-bg: var(--tuc-accent); --tuc-tip-fg: var(--tuc-accent-fg); }
.tip-danger { --tuc-tip-bg: var(--tuc-danger-fill); --tuc-tip-fg: #fff; }
.tip-light  { --tuc-tip-bg: var(--tuc-bg); --tuc-tip-fg: var(--tuc-fg); box-shadow: var(--tuc-shadow); }

<button data-tuc-tip="Solo los administradores pueden eliminar" data-tip-class="tip-danger">Eliminar</button>

Cuándo aparece y cuándo desaparece

Solo una pista queda abierta a la vez: abrir otra cierra la anterior.

Lo que pasa	La pista
El puntero entra	Aparece después de `delay`, 350 ms
El puntero sale	Desaparece después de `delayOut`, 120 ms
El elemento recibe el foco por teclado	Aparece al instante
El foco vuelve después de un clic, como al cerrar un modal	No aparece
El foco sale	Desaparece
Toque, en pantalla táctil	Tocar abre y cierra; tocar fuera cierra
`Esc`	Desaparece, incluso con el puntero quieto encima
El disparador sale de la pantalla al desplazarse	Desaparece, en lugar de quedarse pegada al borde

Accesibilidad

El globo es un role="tooltip", y el elemento apunta a él con aria-describedby: el lector de pantalla lee la pista junto con el botón, como su descripción, y no como un elemento perdido en la página.

Esc cierra con el puntero encima

No es un detalle: es lo que pide la WCAG 1.4.13, para quien usa ampliación de pantalla y necesita quitar de en medio una pista que tapa el contenido sin mover el ratón.

La pista es solo texto y no recibe el puntero. Un enlace, un botón o información que la persona necesita para terminar la tarea no caben en ella: quien no apunta ni enfoca ese elemento nunca la va a ver. La flecha es decorativa y lleva aria-hidden. Con prefers-reduced-motion la pista aparece y desaparece sin animación.

API

Generada a partir del código en cada build — si algo no está aquí, no existe.

Marcado

[data-tuc-tip]

En JS

new Tucano.Tooltip(alvo, opcoes)

Atributos

data-delay data-placement data-tip-class data-tuc-tip

Métodos

setText destroy

Opciones

Las notas de esta tabla salen de los comentarios del código fuente, que están escritos en portugués.

Opción	Por defecto	Para qué
`text`	`''`
`placement`	`'top-center'`
`delay`	`350`	atraso ao apontar: evita piscar ao passar o mouse de raspao
`delayOut`	`120`
`maxWidth`	`'16rem'`
`className`	`''`	classe extra no balao, para variar a cor num caso so