Toast

Aviso temporário que confirma uma ação sem tirar a pessoa do lugar.

O Toast confirma o resultado de uma ação rápida, como copiar um link ou publicar a Marca, e some sozinho. Para um problema que exige correção, use Alert inline. Um único Toast.Provider fica na raiz do app; os avisos saem de qualquer lugar com a função toast.

import { Toast, toast } from "@rastreio-x/ui";

Padrão e estados

toast(...) mostra um aviso neutro; toast.info, toast.success, toast.warning e toast.danger aplicam o estado. Cada um some após 4 segundos.

Com descrição e ação

description acrescenta contexto e actionProps traz um botão. Guarde o id para o botão fechar o próprio aviso.

Promessa

toast.promise acompanha uma tarefa: carregando, depois sucesso ou erro, no mesmo aviso.

Persistente

timeout: 0 mantém o aviso até a pessoa fechar. Use só quando houver o que decidir.

No Admin

Copiar é uma ação rápida: confirme por toast e, se falhar, diga o que fazer.

Configurar o Provider

Renderize Toast.Provider uma vez na raiz. O Admin usa o padrão; placement, maxVisibleToasts e width ajustam a pilha.

import { Toast } from "@rastreio-x/ui";

export function Root({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <Toast.Provider />
    </>
  );
}

Anatomia

Toast
├── Toast.ActionButton
├── Toast.CloseButton
├── Toast.Content
├── Toast.Description
├── Toast.Indicator
├── Toast.Provider
└── Toast.Title

Toast.Indicator: ícone do estado.
Toast.Content, Toast.Title e Toast.Description: o texto.
Toast.ActionButton e Toast.CloseButton: ação e fechar.
Toast.Provider: a região que empilha os avisos.

Propriedades

Provider (Toast.Provider):

Toast.Provider
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	`'Notifications'`	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`children`	`React.ReactNode \| ((renderProps: { toast: QueuedToast<T>; }) => React.ReactElem…`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<ToastRegionRenderProps<T>>`	`'react-aria-ToastRegion'`	Classes CSS aplicadas ao elemento.
`gap`	`number`	`12`	The gap between toasts in pixels.
`hotkey`	`string[]`	`["altKey", "KeyT"]`	Hotkey that focuses the toast region. Modifiers match KeyboardEvent boolean props, other keys match event.code. Modifiers left out must be up, so Alt+T does not fire on Ctrl+Alt+T. Pass [] to disable.
`isExpanded`	`boolean`	`false`	Estado expandido (controlado).
`maxVisibleToasts`	`number`	`3`	The maximum number of toasts to display at a time (visual only).
`placement`	`'top' \| 'bottom' \| 'bottom start' \| 'bottom end' \| 'top start' \| 'top end'`	`"bottom"`	Lado ou posição em que o elemento aparece.
`queue`	`ToastQueue<T>`	-	Fila de toasts criada com `ToastQueue`, para disparar avisos de fora da árvore.
`render`	`DOMRenderFunction<'div', ToastRegionRenderProps<T>>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`scaleFactor`	`number`	`0.05`	How much each toast behind the front one scales down.
`style`	`StyleOrFunction<ToastRegionRenderProps<T>>`	-	Estilos em linha aplicados ao elemento.
`width`	`string \| number`	`460`	The width of the toast; numbers are pixels.

Aviso (Toast):

Toast
Prop	Tipo	Padrão	Descrição
`toast`*	`QueuedToast<T>`	-	The toast object.
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`children`	`ChildrenOrFunction<ToastRenderProps<T>>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<ToastRenderProps<T>>`	`'react-aria-Toast'`	Classes CSS aplicadas ao elemento.
`placement`	`'top' \| 'bottom' \| 'bottom start' \| 'bottom end' \| 'top start' \| 'top end'`	-	Lado ou posição em que o elemento aparece.
`ref`	`React.Ref<HTMLDivElement \| null>`	-	Referência ao elemento DOM.
`render`	`DOMRenderFunction<'div', ToastRenderProps<T>>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`scaleFactor`	`number`	`0.05`	How much each toast behind the front one scales down. Inherited from the provider when omitted.
`style`	`StyleOrFunction<ToastRenderProps<T>>`	-	Estilos em linha aplicados ao elemento.
`variant`	`'danger' \| 'success' \| 'default' \| 'accent' \| 'warning'`	-	Variante visual do componente.

Animações

CSS
indicativo

Os avisos entram e saem com opacity e transform, empilham com leve escala e se reorganizam ao fechar um deles. Os temporizadores pausam ao passar o mouse ou focar. Com prefers-reduced-motion, a folha global da fachada reduz as transições a 0,01 ms.

Acessibilidade

Os avisos ficam numa região de referência nomeada: F6 chega a ela e Alt + T move o foco direto.
Cada aviso é um alertdialog com título e descrição ligados, e é anunciado ao surgir.
Tab alcança os botões dos avisos visíveis; Esc recolhe a pilha.
O tempo de 4 segundos pausa com hover, foco ou aba em segundo plano; não coloque nele informação que só existe ali.

Boas práticas

Faça

Mensagem curta no passado: Link copiado. Marca publicada.

Evite

Usar toast para erro que exige correção, ou deixar uma mensagem fixa na página que nunca some.

Um aviso por ação; não dispare vários seguidos.
Para problemas ligados ao contexto, prefira Alert perto do campo ou do bloco.
Dê um botão de ação (Desfazer) quando reverter for possível.
Texto sem caixa alta; sem "Sucesso!" genérico.

Relacionados

Alert para problemas que ficam na tela.
AlertDialog para confirmar antes de agir.
Button que dispara a ação e o aviso.