Tooltips modernos con CSS Anchor Positioning

Crea tooltips sin JavaScript, posicionamiento nativo con CSS Anchor Positioning, ~0,5 kb y fallback automático.

Seguramente alguna vez habrás notado cómo componentes de una página web interactúan con el puntero del mouse, mostrando un pequeño globo informativo que describe el elemento sobre el cual estás posicionado; este elemento flotante se lo conoce como tooltip.

Hoy te comparto la versión 5 de mi librería de tooltips en CSS puro, sin JavaScript, sin dependencias y sin configuración. Ahora con CSS Anchor Positioning nativo para un posicionamiento dinámico real, llegando a pesar solo ~0,5 kb comprimidos con Brotli.

¿Por qué esta librería en lugar de una basada en JavaScript?

La mayoría de las librerías de tooltips requieren JavaScript para calcular posiciones, adjuntar event listeners y gestionar el estado de visibilidad. Esta librería no hace nada de eso — todo el comportamiento está declarado en CSS.

Características

• CSS puro. Sin JavaScript, dependencias ni configuración.
• Posicionamiento nativo. Usa CSS Anchor Positioning para calcular la posición y cambiar automáticamente de lado cuando no hay espacio.
• Código mínimo. La hoja de estilos contiene solo las reglas necesarias para el comportamiento base; no incluye clases para posiciones, estilos o animaciones que quizá no uses.
• Configuración mediante CSS. Cada tooltip puede definir su posición, apariencia y animación mediante propiedades CSS personalizadas.
• Sin layout shift. El posicionamiento ocurre durante el cálculo del layout del navegador, sin medir el DOM después del renderizado.
• Accesible. Usa aria-label como contenido y muestra los tooltips al recibir :focus.
• Fallback automático. Los navegadores sin CSS Anchor Positioning usan una posición absoluta superior y centrada.

Instalar

npm

npm i @zkreations/tooltips

Frameworks y bundlers

El paquete exporta su CSS minificado como entrada de estilos por defecto, importarlo una sola vez en el punto de entrada de la aplicación:

// app/layout.tsx or pages/_app.tsx
import '@zkreations/tooltips';

---
import '@zkreations/tooltips';
---

import '@zkreations/tooltips';

Si el bundler no resuelve la entrada de estilos del paquete, importa el archivo directamente:

import '@zkreations/tooltips/index.min.css';

Sass

Usa la entrada Sass solo cuando el proyecto necesite compilar el código fuente:

@use '@zkreations/tooltips/scss/tooltip';

CDN

Incluye el archivo index.min.css antes del cierre de </head> mediante la CDN de jsdelivr:

<link href="https://cdn.jsdelivr.net/npm/@zkreations/tooltips@5/index.min.css" rel="stylesheet"/>

Estos tooltips son considerados estilos "no críticos", por lo que, si deseas obtener un mayor rendimiento, te recomiendo diferir la carga de este archivo.

Modo de uso

Añade la clase .tooltip y el atributo aria-label a cualquier elemento HTML:

<button type="button" class="tooltip" aria-label="¡Hola mundo!">
  Pasa el cursor o enfócame
</button>

Posicionamiento

Los tooltips aparecen arriba (block-start) por defecto y se desplazan automáticamente (flip-block, flip-inline) cuando el espacio es insuficiente. Para definir una posición personalizada, sobreescribe la variable --tt-area:

<button type="button" class="tooltip tooltip--bottom" aria-label="Hacia abajo">Hacia abajo</button>
<button type="button" class="tooltip tooltip--right" aria-label="Hacia la derecha">Hacia la derecha</button>
<button type="button" class="tooltip tooltip--left" aria-label="Hacia la izquierda">Hacia la izquierda</button>

.tooltip--right  { --tt-area: inline-end; }
.tooltip--left   { --tt-area: inline-start; }
.tooltip--bottom { --tt-area: block-end; }

Para forzar una posición sin desplazamiento automático:

.tooltip--fixed-right {
  --tt-area: inline-end;
  --tt-fallbacks: none;
}

Visibilidad programática

Agrega el atributo data-tooltip-visible para mostrar el tooltip en cualquier momento sin necesidad de interacción del usuario. Puedes añadir este atributo fácilmente con JavaScript.

<button type="button" class="tooltip" aria-label="Notificación activa" data-tooltip-visible>
  Notificaciones
</button>

Personalizar

Sobreescribe las propiedades CSS para ajustar la apariencia de los tooltips. Las variables disponibles se describen en la siguiente tabla:

Animaciones

Las variables --tt-start y --tt-end aceptan cualquier función de transformación CSS, lo que permite crear animaciones de entrada y salida personalizadas:

.tooltip-slide { --tt-start: translateY(6px) scale(0.9); }
.tooltip-zoom  { --tt-start: scale(0.75); }

Para aplicar una animación por defecto a todos los tooltips:

.tooltip {
  --tt-start: translateY(6px) scale(0.85);
}

Temas personalizados

Las variables permiten crear nuevos temas que puedes aplicar con tus propias clases:

<button type="button" class="tooltip tooltip--custom" aria-label="Tema personalizado">Custom</button>

.tooltip--custom {
  --tt-bg: #2563eb;
  --tt-color: #ffffff;
  --tt-radius: 8px;
  --tt-padding: 8px 12px;
  --tt-shadow: 0 4px 12px rgb(0 0 0 / 15%);
  --tt-gap: 0.5rem;
}

Versión compacta

Si prefieres no utilizar variables CSS y buscas el menor tamaño posible, el proyecto incluye una variante compacta (compact.css / compact.min.css) que conserva el posicionamiento automático mediante CSS Anchor Positioning y el fallback para navegadores no compatibles.

Debido a su reducido tamaño (~1 KB sin minificar / ~800 B minificado), se recomienda copiar directamente el contenido de compact.css en la hoja de estilos de tu proyecto. De este modo puedes editar y personalizar cualquier aspecto visual del tooltip directamente en el CSS, sin recurrir a variables.

Si prefieres importarlo como paquete:

import '@zkreations/tooltips/compact.min.css';

Sin flecha, por diseño

La v5 no incluye una flecha como pseudo-elemento (::after). flip-block y flip-inline cambian la posición de la burbuja sin comunicar el cambio de orientación a los bordes de pseudo-elementos de forma consistente en todos los navegadores, lo que produce errores visuales. Omitir la flecha evita esos errores y mantiene la hoja de estilos más pequeña.

Compatibilidad con navegadores

Los navegadores que soportan CSS Anchor Positioning usan @supports (position-area: block-start) para el posicionamiento dinámico y el desplazamiento automático. Los navegadores sin soporte reciben un fallback estático: una burbuja superior centrada en posición absoluta. Puedes consultar el soporte actual en Can I Use — CSS Anchor Positioning.

Migración de v4 a v5

Si venías usando la versión anterior, estos son los cambios principales:

Conclusión

Llevo trabajando en este proyecto desde el 2016 y personalmente es uno de mis favoritos. Con la v5 damos un salto importante al apoyarnos en CSS Anchor Positioning, lo que elimina completamente la necesidad de JavaScript para el posicionamiento. Puedes comprobar todos los cambios en GitHub.

Comparte este artículo o califica con una estrella el repositorio si este proyecto te ha sido de utilidad, te lo agradeceré enormemente. Cualquier duda déjala en los comentarios, muchas gracias por pasar.