Toast

2.7.1

Notificar de forma breve y temporal el resultado de una acción que acaba de ocurrir o el avance de un proceso, sin interrumpir la navegación.

Ver en Figma

Cuándo usar

Informar el resultado de una acción: avisar justo después de ejecutarla que se completó con éxito o que falló, sin bloquear la pantalla ni requerir una respuesta; usar type="success" o type="danger" según el resultado. Ej.: "Cupón creado.", "Error al exportar. Intentá de nuevo.".
Informar el avance de un proceso en curso: mostrar que una acción sigue en marcha y todavía no tiene un resultado definido de éxito o error; usar type="progress" con autoClose={false} y cerrarlo al finalizar. Ej.: "Eliminando cliente…".
Notificar sobre una acción común: avisar sobre una tarea rutinaria que no es un "logro" pero requiere confirmación visual; usar type="primary" (valor por defecto). Ej.: "Elemento archivado.", "Borrador guardado.".

Cuándo no usar

Comunicar un evento importante que debe permanecer visible: el Toast desaparece solo y el mensaje se pierde si la persona no llega a leerlo. En su lugar, usar Alert.
Interrumpir a la persona para pedir una decisión: el Toast no admite acciones ni bloquea el flujo, por lo que no sirve para pedir que se confirme o descarte algo antes de continuar. En su lugar, usar Modal.
Señalar un error de validación de un campo puntual: el mensaje debe quedar junto al campo que lo origina para que se entienda a qué dato corresponde. En su lugar, usar el estado de error del Input.

Anatomía

Cliente agregado.

Ícono + texto

Eliminando cliente…

Spinner + texto

Surface: contenedor con fondo y borde redondeado; el color de fondo cambia según el type.
Icon: opcional, ubicado antes del texto; refuerza el tipo del mensaje (información, éxito o error) y es mutuamente excluyente con el Spinner.
Text: el mensaje que describe lo que ocurrió o está ocurriendo.
Spinner: opcional; reemplaza al Icon cuando type="progress" para indicar que el proceso sigue en curso.

Variantes

Tipo (type)

Primary

Primary: confirma una acción rutinaria que no es un logro, sin asociarla a éxito ni error; es el valor por defecto. Ej.: "Enlace copiado al portapapeles.", "Producto pausado.".

Success

Success: confirma que una acción se completó con éxito. Ej.: "Cliente agregado.", "Cupón creado.".

Danger

Danger: comunica que una acción falló y suele poder reintentarse. Ej.: "Error al exportar.", "Error al agregar. Intentá de nuevo.".

Progress

Progress: indica un proceso en curso, sin un resultado de éxito o error definido; se usa con autoClose={false} y se cierra manualmente al finalizar. Ej.: "Eliminando cliente…", "Subiendo imágenes…".

Aplicación

El Toast aparece fijo en la parte inferior y centrada de la pantalla, por encima del contenido. Cuando el ToastProvider administra varios a la vez, behavior="stacked" (valor por defecto) los apila y behavior="single" reemplaza el anterior por el nuevo.

Desktop

Se muestra centrado en el borde inferior de la ventana, sin tapar la navegación ni el contenido principal; los mensajes consecutivos se apilan hacia arriba.

Cambios guardados.

Mobile

Mantiene la posición inferior y centrada. Cuando la pantalla tiene una barra de navegación fija en la parte de abajo, usar offset="high" en el ToastProvider para que el Toast quede por encima de esa barra y no la tape.

Subiendo imágenes…

Duración

Elegir la duración (duration) según la cantidad de caracteres del mensaje, para asegurar que se pueda leer por completo antes de que el Toast se cierre.

Duración	Uso
4000 (4 segundos)	Mensajes de hasta 10 caracteres.
8000 (8 segundos)	Mensajes de entre 11 y 20 caracteres.
16000 (16 segundos)	Mensajes de más de 20 caracteres.
Sin cierre automático (autoClose={false})	Uso restringido a type="progress"; cerrar el Toast manualmente cuando el proceso termina.

Todos los ejemplos de Toast en esta página usan autoClose={false} para que se mantengan visibles mientras se lee la documentación; es una configuración solo para la demo, no una recomendación de uso — fuera de type="progress", dejar que el Toast se cierre automáticamente según las duraciones de arriba.

Do and Don'ts

Cupón creado.

Escribir un mensaje breve, en participio pasado, que describa el resultado de la acción.

Error 500: no se pudo persistir la entidad en la base de datos.

Evitar mensajes largos o con jerga técnica que la persona no pueda leer en pocos segundos.

No se pudo eliminar el cupón. Intentá de nuevo.

Elegir el `type` según el resultado real de la acción.

No se pudo eliminar el cupón.

No confundir los colores: cada `type` comunica un resultado distinto y debe coincidir con lo que realmente ocurrió.

Accesibilidad

Información no dependiente solo del color: cada type combina el color de fondo con un ícono que refuerza el significado (información, éxito o error) y un texto que comunica el resultado; quien no distingue los colores igual entiende el mensaje.
Duración acorde a la longitud del texto: ajustar duration (4000, 8000 o 16000 ms) para que el mensaje pueda leerse completo antes de cerrarse. En procesos en curso, usar autoClose={false} y cerrar el Toast manualmente cuando el proceso termina.
No reservar información crítica al Toast: al ser temporal y no recibir foco, no debe ser el único medio para comunicar algo que la persona no puede perderse; para eso usar Alert o Modal.
Texto autoexplicativo sin contexto visual: el type no se anuncia por voz en los lectores de pantalla, solo el texto; el mensaje tiene que comunicar el resultado por sí solo, sin depender del ícono ni del color.
Objeto explícito en progress: incluir el objeto del proceso para que el mensaje sea claro sin ver el ícono. Ej.: "Eliminando cliente…", no "Eliminando…".

Guía de contenido

El texto es un mensaje único: sin artículos innecesarios, sin punto y coma y sin la palabra "exitosamente" (el type y el ícono ya comunican el resultado, así que agregarla es redundante).

Puntuación: con punto final siempre, incluso en mensajes cortos.

Longitud máxima: 30 caracteres para success, primary y progress. danger puede extenderse a 40 caracteres cuando incluye una segunda oración con la salida (ej.: "Intentá de nuevo.").

Forma verbal según el tipo:

Type	Cuándo usarlo	Fórmula	Ejemplo
success	Una acción se completó con éxito.	[Sustantivo] + [participio pasado]	"Cliente agregado.", "Cambios guardados."
danger	Una acción falló y puede reintentarse.	Error al + [infinitivo] (+ acción opcional)	"Error al exportar.", "Error al agregar. Intentá de nuevo."
progress	Un proceso está en curso.	[Gerundio] + [objeto]	"Eliminando cliente…", "Subiendo imágenes…"
primary	Un aviso que merece atención sin implicar éxito ni error.	[Sustantivo] + [participio pasado]	"Solicitud enviada.", "Actualización disponible."

El gerundio queda reservado para progress: en success y primary siempre va participio pasado, nunca infinitivo ni gerundio.

Casos críticos

Caso	Qué hacer	Qué no hacer
El mensaje supera el límite de su tipo (30 caracteres, o 40 en `danger` con una segunda oración)	Reescribirlo. Si la información no puede resumirse, usar Alert.	Dejar un mensaje largo que la persona no llega a leer antes de que se cierre.
El error requiere una acción inmediata de la persona	No usar Toast: usar Modal o Alert.	Comunicar un error crítico solo con un Toast que se cierra solo.
El proceso en curso termina (con éxito o con error)	Cerrar el Toast de progress y disparar uno nuevo de success o danger.	Dejar el Toast de progress abierto después de que el proceso terminó.
El mensaje necesita un link	Usar Alert: el Toast no admite acciones ni links.	Incluir un link inline dentro del texto del Toast.

Implementación

Instalá el componente vía terminal.

npm install @nimbus-ds/components

Configuración y uso básico. El ToastProvider se coloca en la raíz de la aplicación para que el hook useToast esté disponible en todos los niveles. Desde cualquier componente por debajo del Provider, addToast genera un nuevo Toast.

import React from "react";
import { ToastProvider, useToast, Button } from "@nimbus-ds/components";

const App: React.FC = () => (
  <ToastProvider>
    <Home />
  </ToastProvider>
);

const Home: React.FC = () => {
  const { addToast } = useToast();
  return (
    <Button
      onClick={() =>
        addToast({
          id: "save-success",
          type: "success",
          text: "Cambios guardados.",
          duration: 8000,
        })
      }
    >
      Guardar cambios
    </Button>
  );
};

Configuración con ToastProvider y el hook useToast.

import React from "react";
import { ToastProvider, useToast, Button } from "@nimbus-ds/components";

const Example: React.FC = () => (
  <ToastProvider>
    <App />
  </ToastProvider>
);

const App: React.FC = () => {
  const { addToast } = useToast();
  return (
    <Button
      onClick={() => {
        addToast({
          id: "my-toast",
          type: "primary",
          text: "Toast",
          duration: 4000,
        });
      }}
    >
      Add toast
    </Button>
  );
};

export default Example;

Props

Las propiedades adicionales se pasan al elemento <Toast>. Consultá la documentación del elemento div para ver la lista de atributos aceptados.

Componentes relacionados

Alert — para notificar de forma persistente un evento importante que requiere la acción de la persona.
Modal — para interrumpir la navegación y pedir una decisión basada en algo que acaba de ocurrir.

Toast

Name	Type	Default	Description
id*	string		Unique toast ID used when hiding or removing a toast.
text*	string		The text that should appear in the toast message.
type	'danger' 'primary' 'progress' 'success'	'primary'	Change the visual style of the toast.
duration	'16000' '4000' '8000'	'4000'	The time in milliseconds that the toast message should persist.
autoClose	boolean	'true'	Tells you whether or not Toast should close automatically.
position	number	'0'	Tells the toast position when we are using multiple toasts.

Toast.Provider

Name	Type	Default	Description
children*	React.ReactNode
offset	'default' 'high'	'default'	Controls the vertical offset of the toast container from the bottom. Use "high" for mobile apps with bottom navigation bars.
behavior	'single' 'stacked'	'stacked'	Controls how multiple toasts are handled. "stacked" - new toasts are piled up alongside already rendered ones. "single" - only one toast is shown at a time; each new toast immediately replaces the previous one.

Ayudanos a mejorar la documentación

¿Encontraste un problema o tenés una sugerencia? Contanos.

Compartí tu opinión