Saltar al contenido

Toast

Notificaciones efímeras apiladas en una esquina. Se disparan de dos formas: desde el HTML, con un botón data-ts-toast-trigger, o desde el JS propio con la función toast(), importada del mismo taisho.core.js, con la variante que corresponda (éxito, advertencia, peligro, info). Se pega el contenedor del ejemplo: trae los íconos de cada variante. Sin él, el Core crea uno con el primer aviso: los avisos salen sin ícono y ese primer aviso puede no anunciarse con el lector de pantalla. Cada aviso puede llevar una acción («Deshacer»), se pausa mientras el puntero o el foco están encima y se puede actualizar por id.

Avisos y estado · TaishoDS Core, en HTML plano.

Ejemplos

Un ejemplo por caso, funcionando. Cada ejemplo es el HTML de su vista previa: se copia tal cual y, con el CSS y el JS del Core cargados, se ve y funciona igual.

Aviso al guardar

html

Referencia de clases

Todos los valores de cada modificador, con su HTML listo para copiar.

Variante

El color según el tono del aviso: default, success, warning, info o danger.

Nueva versión disponible.
Despliegue completado.
Tu plan está por vencer.
Cambios guardados.
No pudimos procesar el pago.
html

Posición

En qué esquina aparece: top/bottom × left/center/right.

Despliegue completado.
Despliegue completado.
Despliegue completado.
Despliegue completado.
Despliegue completado.
Despliegue completado.
html

Acción

Con un botón de acción (por ejemplo «Deshacer»): al usarlo se ejecuta tu callback y el aviso se cierra.

Proyecto movido a la papelera.
html

Cuándo usarlo

  • Confirmar el resultado de una acción que el usuario acaba de hacer: “Guardado”, “Copiado”.
  • El aviso no exige respuesta y puede irse solo a los pocos segundos.
  • El disparador está en el código (después de un await), no en el HTML.
  • Una acción reversible («Proyecto eliminado» + Deshacer) o un proceso que cambia de estado: «En cola» → «Construyendo» → «Listo».

Cuándo no

  • El mensaje tiene que quedar a la vista hasta que se resuelva → banner o note.
  • Hay que decidir algo antes de seguir → alert-dialog.
  • Es el error de un campo: va en el campo, no en una esquina → field.

Cómo usarlo

  • Se disparan con data-ts-toast-trigger en un botón o con toast() desde el código, y se pega el contenedor del ejemplo: sin él los avisos salen sin ícono.
  • Mensajes de una línea; si necesita más texto (la opción description), conviene evaluar si no es un banner o una note.
  • Un error que el usuario tiene que leer entero: duration: 0 para que no se vaya solo.
  • Para una operación async, se actualiza el mismo aviso por su id en vez de disparar uno por cada paso (toast.promise, o updateToast con el aviso o su id).
  • Con action, conviene darle más tiempo (duration de 6000 ms o más): el aviso se pausa con el puntero o el foco encima, pero no todos los usuarios llegan a tiempo.

Cómo no usarlo

  • No se pone ahí lo único que explica un error grave: se va y no vuelve.
  • No se dispara una ráfaga de toasts por una sola acción.
  • No se pone en action lo único que permite completar la tarea: si el aviso se va, la acción también.

TaishoDS Core

Necesita el JS del Core: maneja foco, teclado y estado.

Los avisos se crean en el momento: desde un botón con data-ts-toast-trigger o desde tu JS con toast(). El contenedor trae los íconos de cada variante.

El Core lo engancha por estos atributos. Van en el marcado; no hace falta inicializar nada.

  • data-ts-toast-container
  • data-ts-toast-dismiss-label
  • data-ts-toast-icon
  • data-ts-toast-region
  • data-ts-toast-trigger
  • data-ts-toast-variant

Qué hace: Cola con temporizadores y apilado; pausa del temporizador con el puntero encima o el foco adentro (retoma desde lo que faltaba); botón de acción con callback; description (detalle bajo el título); updateToast para cambiar un aviso por su elemento o su id; toast.promise(promesa, { loading, success, error }), un solo aviso que pasa de cargando a éxito o error; y dos regiones vivas (cortés y asertiva, esta última para danger). Hay dos formas de disparar un aviso: desde el HTML, o desde el JS propio con toast(), importada del mismo taisho.core.js. Se pega el contenedor del ejemplo: trae los íconos de cada variante. Sin él, el Core crea uno, pero los avisos salen sin ícono.

Atributo Qué hace
--ts-toaster-offsetVariable CSS del contenedor (o de cualquier ancestro): espacio extra desde el borde de la posición, para no tapar una barra fija al pie (cookies, reproductor) o arriba. Por defecto 0px. Se suma al margen y al env(safe-area-inset-*) del dispositivo. Ejemplo: :root { --ts-toaster-offset: 72px }; si la barra cambia de alto según el ancho, se cambia la variable en una @media. Para que el área segura valga algo, la página necesita viewport-fit=cover en su meta viewport.
data-ts-toast-trigger="Texto"En un botón: al hacer clic muestra un aviso con ese texto.
data-ts-toast-variantEn el mismo botón: default (por defecto), success, warning, info o danger.
data-ts-toast-containerEl contenedor de los avisos; trae dos regiones vivas, una cortés y una asertiva (data-ts-toast-region). Con las <template data-ts-toast-icon="…"> que trae el ejemplo, cada variante lleva su ícono.
data-ts-toast-dismiss-labelEn el contenedor: el nombre accesible del botón de cerrar de cada aviso. Sin él, «Cerrar notificación». La opción dismissLabel de toast() lo cambia para un aviso.
toast(message, options)Desde tu JS: muestra un aviso y devuelve su elemento. toast.promise() y updateToast() lo siguen y lo cambian.

Sin build, desde el CDN: taisho.toast.css, además de taisho.base.css. También se carga:

  • taisho.button.css
  • taisho.icon.css
  • taisho.spinner.css

Para el funcionamiento general del Core, ver Comportamiento.

Accesibilidad

  • El contenedor trae dos regiones vivas hermanas desde el marcado: una cortés (role="status") y una asertiva (role="alert"). Existen antes del primer aviso, que es lo que permite que se anuncie de forma fiable. Los avisos de error (variante danger) van a la asertiva y el resto a la cortés; los avisos no llevan rol propio, así que no hay regiones anidadas. Sin el contenedor en el marcado, el Core lo crea junto con el primer aviso y ese primer anuncio puede no leerse.
  • El color no es el único indicador: el texto comunica el estado, y el ícono de variante lo refuerza cuando el contenedor trae las <template data-ts-toast-icon> del ejemplo. Sin ese contenedor los avisos salen sin ícono, y el texto sigue diciendo el estado.
  • Tiempo ajustable (WCAG 2.2.1): los avisos se pausan mientras el puntero está sobre la región de avisos o el foco está dentro, y retoman desde lo que faltaba; duration: 0 los deja hasta que se cierren.
  • La acción (Deshacer) es un <button> real: Tab llega a él, Enter o Espacio lo activan y cierran el aviso.
  • Al actualizar un aviso por id, el texto nuevo se anuncia por la región en que está; si la variante pasa a ser de error (danger), el aviso se muda a la región asertiva (y vuelve a la cortés si deja de serlo). Durante toast.promise el aviso lleva aria-busy y el Spinner es decorativo (aria-hidden).

Verificación

Qué se probó de verdad. Lo que no se probó lo dice: preferimos un «sin verificar» a una afirmación de más.

  • axe WCAG 2.2 A + AA en navegador real, en tema claro y oscuro, antes de cada versión.
  • teclado No agrega teclas propias: usa el comportamiento nativo del navegador.
  • lector de pantalla Sin verificar con lector de pantalla. Conviene probarlo en la combinación de componentes propia, no sólo aquí, donde cada uno aparece solo y en su estado feliz.