Toast

2.7.1

Notificar de forma breve e temporária o resultado de uma ação que acabou de ocorrer ou o andamento de um processo, sem interromper a navegação.

Ver no Figma

Quando usar

Informar o resultado de uma ação: avisar, logo após executá-la, que foi concluída com sucesso ou que falhou, sem bloquear a tela nem exigir uma resposta; usar type="success" ou type="danger" conforme o resultado. Ex.: "Cupom criado.", "Erro ao exportar. Tente novamente.".
Informar o andamento de um processo em curso: mostrar que uma ação continua em andamento e ainda não tem um resultado definido de sucesso ou erro; usar type="progress" com autoClose={false} e fechá-lo ao finalizar. Ex.: "Excluindo cliente…".
Notificar sobre uma ação comum: avisar sobre uma tarefa rotineira que não é uma "conquista", mas exige confirmação visual; usar type="primary" (valor padrão). Ex.: "Item arquivado.", "Rascunho salvo.".

Quando não usar

Comunicar um evento importante que deve permanecer visível: o Toast desaparece sozinho e a mensagem se perde se a pessoa não chegar a lê-la. Em vez disso, usar Alert.
Interromper a pessoa para pedir uma decisão: o Toast não admite ações nem bloqueia o fluxo, por isso não serve para pedir que se confirme ou descarte algo antes de continuar. Em vez disso, usar Modal.
Sinalizar um erro de validação de um campo específico: a mensagem deve ficar junto ao campo que a origina para que fique claro a qual dado corresponde. Em vez disso, usar o estado de erro do Input.

Anatomia

Cliente adicionado.

Ícone + texto

Excluindo cliente…

Spinner + texto

Surface: contêiner com fundo e borda arredondada; a cor do fundo muda conforme o type.
Icon: opcional, posicionado antes do texto; reforça o tipo da mensagem (informação, sucesso ou erro) e é mutuamente exclusivo com o Spinner.
Text: a mensagem que descreve o que aconteceu ou está acontecendo.
Spinner: opcional; substitui o Icon quando type="progress" para indicar que o processo continua em curso.

Variantes

Tipo (type)

Primary

Primary: confirma uma ação rotineira que não é uma conquista, sem associá-la a sucesso nem erro; é o valor padrão. Ex.: "Link copiado para a área de transferência.", "Produto pausado.".

Success

Success: confirma que uma ação foi concluída com sucesso. Ex.: "Cliente adicionado.", "Cupom criado.".

Danger

Danger: comunica que uma ação falhou e costuma poder ser refeita. Ex.: "Erro ao exportar.", "Erro ao adicionar. Tente novamente.".

Progress

Progress: indica um processo em curso, sem um resultado de sucesso ou erro definido; é usado com autoClose={false} e fechado manualmente ao finalizar. Ex.: "Excluindo cliente…", "Enviando imagens…".

Aplicação

O Toast aparece fixo na parte inferior e centralizada da tela, acima do conteúdo. Quando o ToastProvider administra vários ao mesmo tempo, behavior="stacked" (valor padrão) os empilha e behavior="single" substitui o anterior pelo novo.

Desktop

É exibido centralizado na borda inferior da janela, sem cobrir a navegação nem o conteúdo principal; as mensagens consecutivas se empilham para cima.

Dados salvos.

Mobile

Mantém a posição inferior e centralizada. Quando a tela tem uma barra de navegação fixa na parte inferior, usar offset="high" no ToastProvider para que o Toast fique acima dessa barra e não a cubra.

Enviando imagens…

Duração

Escolher a duração (duration) conforme a quantidade de caracteres da mensagem, para garantir que possa ser lida por completo antes de o Toast se fechar.

Duração	Uso
4000 (4 segundos)	Mensagens de até 10 caracteres.
8000 (8 segundos)	Mensagens entre 11 e 20 caracteres.
16000 (16 segundos)	Mensagens com mais de 20 caracteres.
Sem fechamento automático (autoClose={false})	Uso restrito a type="progress"; fechar o Toast manualmente quando o processo terminar.

Todos os exemplos de Toast nesta página usam autoClose={false} para permanecerem visíveis durante a leitura da documentação; é uma configuração apenas da demo, não uma recomendação de uso — fora de type="progress", deixar o Toast fechar automaticamente conforme as durações acima.

Do and Don'ts

Cupom criado.

Escrever uma mensagem breve, no particípio passado, que descreva o resultado da ação.

Erro 500: não foi possível persistir a entidade no banco de dados.

Evitar mensagens longas ou com jargão técnico que a pessoa não consiga ler em poucos segundos.

Não foi possível excluir o cupom. Tente novamente.

Escolher o `type` conforme o resultado real da ação.

Não foi possível excluir o cupom.

Não confundir as cores: cada `type` comunica um resultado diferente e deve corresponder ao que realmente aconteceu.

Acessibilidade

Informação não dependente apenas da cor: cada type combina a cor de fundo com um ícone que reforça o significado (informação, sucesso ou erro) e um texto que comunica o resultado; quem não distingue as cores ainda assim entende a mensagem.
Duração de acordo com o tamanho do texto: ajustar duration (4000, 8000 ou 16000 ms) para que a mensagem possa ser lida por completo antes de fechar. Em processos em curso, usar autoClose={false} e fechar o Toast manualmente quando o processo terminar.
Não reservar informação crítica ao Toast: por ser temporário e não receber foco, não deve ser o único meio de comunicar algo que a pessoa não pode perder; para isso, usar Alert ou Modal.
Texto autoexplicativo sem contexto visual: o type não é anunciado por voz pelos leitores de tela, só o texto; a mensagem precisa comunicar o resultado por si só, sem depender do ícone nem da cor.
Objeto explícito em progress: incluir o objeto do processo para que a mensagem fique clara sem ver o ícone. Ex.: "Excluindo cliente…", não "Excluindo…".

Guia de conteúdo

O texto é uma mensagem única: sem artigos desnecessários, sem ponto e vírgula e sem a palavra "com sucesso" (o type e o ícone já comunicam o resultado, incluí-la é redundante).

Pontuação: com ponto final sempre, mesmo em mensagens curtas.

Tamanho máximo: 30 caracteres para success, primary e progress. danger pode chegar a 40 caracteres quando inclui uma segunda frase com a saída (ex.: "Tente novamente.").

Forma verbal conforme o tipo:

Type	Quando usar	Fórmula	Exemplo
success	Uma ação foi concluída com sucesso.	[Substantivo] + [particípio passado]	"Cliente adicionado.", "Alterações salvas."
danger	Uma ação falhou e pode ser refeita.	Erro ao + [infinitivo] (+ ação opcional)	"Erro ao exportar.", "Erro ao adicionar. Tente novamente."
progress	Um processo está em curso.	[Gerúndio] + [objeto]	"Excluindo cliente…", "Enviando imagens…"
primary	Um aviso que merece atenção sem implicar sucesso nem erro.	[Substantivo] + [particípio passado]	"Solicitação enviada.", "Atualização disponível."

O gerúndio fica reservado para progress: em success e primary vai sempre particípio passado, nunca infinitivo nem gerúndio.

Casos críticos

Caso	O que fazer	O que não fazer
A mensagem passa do limite do seu tipo (30 caracteres, ou 40 em `danger` com uma segunda frase)	Reescrever. Se a informação não puder ser resumida, usar Alert.	Deixar uma mensagem longa que a pessoa não consegue ler antes de fechar.
O erro exige uma ação imediata da pessoa	Não usar Toast: usar Modal ou Alert.	Comunicar um erro crítico apenas com um Toast que se fecha por conta própria.
O processo em curso termina (com sucesso ou com erro)	Fechar o Toast de progress e disparar um novo de success ou danger.	Deixar o Toast de progress aberto depois que o processo terminou.
A mensagem precisa de um link	Usar Alert: o Toast não admite ações nem links.	Incluir um link inline dentro do texto do Toast.

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/components

Configuração e uso básico. O ToastProvider é colocado na raiz da aplicação para que o hook useToast esteja disponível em todos os níveis. A partir de qualquer componente abaixo do Provider, addToast gera um novo 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: "Dados salvos.",
          duration: 8000,
        })
      }
    >
      Salvar alterações
    </Button>
  );
};

Configuração com ToastProvider e o 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

As propriedades adicionais são repassadas ao elemento <Toast>. Consulte a documentação do elemento div para ver a lista de atributos aceitos.

Componentes relacionados

Alert — para notificar de forma persistente um evento importante que exige a ação da pessoa.
Modal — para interromper a navegação e pedir uma decisão com base em algo que acabou de acontecer.

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.

Ajude-nos a melhorar a documentação

Encontrou um problema ou tem uma sugestão? Conte para a gente.

Compartilhe seu feedback