Toast Nuevo

El componente hp-toast proporciona notificaciones no-modales que se muestran temporalmente y desaparecen automáticamente. Implementa role="alert" con aria-live="polite" para máxima accesibilidad con screen readers.

Demostración

Sin estilos (solo base.css)

Así se ve hp-toast usando únicamente @headless-primitives/utils/base.css. El auto-dismiss y los eventos funcionan completamente sin ningún estilo visual.

Con estilos personalizados

index.html

<hp-toast-container data-position="bottom-right"></hp-toast-container>

<button id="show-success">Éxito</button>
<button id="show-error">Error</button>

<script>
  const container = document.querySelector("hp-toast-container");

  document.getElementById("show-success").addEventListener("click", () => {
    container.addToast("✓ Cambios guardados", { duration: 3000 });
  });

  document.getElementById("show-error").addEventListener("click", () => {
    container.addToast("✗ Error al guardar", { duration: 4000 });
  });
</script>

style.css

hp-toast {
  padding: 0.75rem 1rem;
  border-radius: 6px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  font-size: 0.875rem;
  min-width: 220px;
}

Instalación

pnpm

pnpm add @headless-primitives/toast

npm

npm install @headless-primitives/toast

yarn

yarn add @headless-primitives/toast

bun

bun add @headless-primitives/toast

Features

• ♿️ role="alert", aria-live="polite" y aria-atomic="true" automáticos.
• ⏱️ Auto-dismiss configurable con data-duration (default 3000ms, 0 = manual).
• 🎨 Sin estilos visuales (Headless).
• 📐 Container con posicionamiento configurable (data-position).
• 🔄 API programática para agregar y limpiar toasts dinámicamente.

Anatomía

<hp-toast-container>
  <hp-toast>
    <hp-toast-title></hp-toast-title>
    <hp-toast-description></hp-toast-description>
    <hp-toast-close></hp-toast-close>
  </hp-toast>
</hp-toast-container>

API Reference

hp-toast

Elemento individual que representa una notificación.

Atributos / Propiedades

Atributo / Propiedad	Tipo	Por Defecto	Descripción
data-duration	number	3000	Milisegundos antes del auto-dismiss. 0 = solo cierre manual.

Métodos

Método	Descripción
close()	Cierra el toast programáticamente.

Eventos

Evento	Detalle	Descripción
hp-dismiss	—	Se dispara cuando el toast se ha cerrado y removido del DOM.

Atributos ARIA gestionados automáticamente

• role="alert" — Siempre presente.
• aria-live="polite" — Notifica cambios a assistive technology.
• aria-atomic="true" — Anuncia el contenido completo.
• data-state — "open" | "closed".

hp-toast-container

Contenedor para múltiples toasts con layout y posicionamiento.

Atributos / Propiedades

Atributo / Propiedad	Tipo	Por Defecto	Descripción
data-position	string	"bottom-right"	Posición en viewport: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right.

Métodos

Método	Descripción
addToast(content, options?)	Crea y añade un toast nuevo. Retorna el HeadlessToast.
clearAll()	Cierra todos los toasts en el container.

hp-toast-title

Título del toast.

hp-toast-description

Descripción del toast.

hp-toast-close

Botón de cierre del toast.

Atributos ARIA gestionados automáticamente

• role="button" — Asignado si no se especifica.
• tabindex="0" — Siempre focusable.

Accesibilidad

Adhiere al patrón WAI-ARIA Alert.

Navegación por teclado

Tecla	Acción
Enter / Space	Activa el botón de cierre (hp-toast-close).