Toast · Documentation

UIToast

Rétroaction non bloquante pour les actions produitLien vers la section

Les Toast Le composant affiche des commentaires courts, temporaires et non bloquants.

Utilisez-le pour :

Confirmer les actions
Résumer les résultats
afficher de courts messages système
fournir une réessai légère ou annuler les commentaires
Reconnaître l'intention de l'utilisateur sans interrompre le flux

Toast est intentionnellement minime dans PyColors UI.

Il fournit une structure et une accessibilité, et non un système de notification complet avec des files d'attente, des magasins globaux, du dédoublonnage ou un historique de notification persistant.

Idée de base

Les toasts sont des commentaires temporaires. Ils devraient confirmer, résumer ou récupérer - ne pas bloquer la tâche.

ImportationLien vers la section

toast-import.tsx

import { Toast } from "@pycolors/ui";

Utilisation de baseLien vers la section

Toast est contrôlé explicitement par la page ou le composant.

Enveloppez votre application, votre route ou votre sous-arbre de mise en page avec ToastProvider, puis rendre une ToastViewport par étendue de fournisseur.

Loading preview…

Règle du fournisseur

Rendre un ToastViewport par étendue de fournisseur. Évitez de rendre une fenêtre d'affichage à l'intérieur de chaque composant de fonctionnalité.

Quand utiliser ToastLien vers la section

Utilisez Toast lorsque le feedback doit être perceptible mais ne doit pas interrompre l'utilisateur.

Confirmation

Confirmez qu’une action d’enregistrement, de mise à jour, d’archivage ou d’arrière-plan est terminée.

Réessayer ou annuler

Offrez une récupération légère pour les actions réversibles ou les mises à jour d'arrière-plan échouées.

Feedback système

Afficher des commentaires système courts qui n'appartiennent pas en permanence à la page.

VariantesLien vers la section

Toast prend en charge un petit ensemble de variantes. Les variantes de succès, d'avertissement et de destruction utilisent des couleurs de bordure sémantiques avec le texte de premier plan normal, préservant ainsi le contraste lisible des messages dans les deux thèmes. Inclure un titre descriptif ou un message afin que la signification ne dépende pas uniquement de la couleur. Consommateur className Les surcharges ont toujours préséance.

Gardez les variantes limitées pour éviter de transformer chaque message en événement.

Loading preview…

Variantes disponiblesLien vers la section

Variante	Objet
`default`	Confirmation ou information neutre
`success`	Confirmation positive
`warning`	Attention nécessaire, toujours non bloquante
`destructive`	Feedback d'erreur non bloquant
`info`	Message d'information - annonce poliment (non affirmatif)

Variante de règle

Utilisation destructive uniquement pour les défaillances récupérables ou non bloquantes. Utilisez Alert pour bloquer les erreurs.

Avec descriptionLien vers la section

Utilisation ToastDescription Quand le titre seul ne suffit pas.

toast-description.tsx

<Toast variant="warning">
  <ToastTitle>Unsaved changes</ToastTitle>
  <ToastDescription>
    Save before leaving this page to avoid losing your work.
  </ToastDescription>
</Toast>

Gardez la description courte.

Si le message a besoin de plus d'explications, il appartient probablement à une section Alerte, Boîte de dialogue ou page.

UtilisationsLien vers la section

Déclenchement après le début ou la fin de l'action

Utilisez la rétroaction après une action significative : sauvegardée, archivée, restaurée, copiée, échouée ou mise en file d'attente.

Gardez le message court

Les toasts sont temporaires. L’utilisateur doit les comprendre d’un seul coup d’œil.

Utiliser l'état inline pour un travail actif

Pour le chargement ou la soumission, préférez le texte de bouton tel que Saving… avant de porter le toast final.

Utilisez les actions de récupération avec précaution

Annuler et réessayer fonctionnent bien pour les actions réversibles, mais elles nécessitent un véritable support backend.

Toast vs Alerte vs DialogueLien vers la section

Situation	Utilisation
Enregistrer la confirmation	Toast
Copie au presse-papiers	Toast
Synchronisation d'arrière-plan terminée	Toast
Erreur de page de blocage	Alerte
Problème de validation au niveau du formulaire	Alerte
Confirmation destructive	boîte dialogue
L'utilisateur doit choisir avant de continuer	boîte dialogue

Règle de décision

Toast est pour la rétroaction après un flux. L'alerte est pour l'information à l'intérieur d'un flux. La boîte de dialogue sert à bloquer les décisions.

Guide des produitsLien vers la section

Enregistrer la confirmation

Use toast feedback after the save completes. Keep loading state inline on the submit button.

Changes saved successfully.

APILien vers la section

Prop	Type	Par défaut	Désignation
`variant`	`"default" \| "success" \| "warning" \| "destructive"`	`"default"`	Style visuel
`open`	`boolean`	—	État ouvert contrôlé
`onOpenChange`	`(open: boolean) => void`	—	Gestionnaire d'État
`duration`	`number`	Radix par défaut	Délai de fermeture automatique en millisecondes
`className`	`string`	—	Classes Tailwind personnalisées

Toast s'étend Radix Toast racine accessoires:

toast-types.ts

React.ComponentPropsWithoutRef<typeof ToastPrimitive.Root>;

ToastProviderLien vers la section

Enveloppe la zone où les toasts sont utilisés.

toast-provider.tsx

<ToastProvider>{/* app or route subtree */}</ToastProvider>

ToastViewportLien vers la section

Définit où les toasts apparaissent à l'écran.

Rendre un viewport par portée de fournisseur.

toast-viewport.tsx

<ToastViewport className="fixed bottom-4 right-4 z-50 flex max-w-sm flex-col gap-2 outline-none" />

TypeScript typesLien vers la section

toast-types.ts

export type ToastVariant = "default" | "success" | "warning" | "destructive";

export interface ToastProps
  extends
    React.ComponentPropsWithoutRef<typeof ToastPrimitive.Root>,
    VariantProps<typeof toastVariants> {}

AccessibilitéLien vers la section

Toast est construit sur les primitives Radix Toast.
Les toasts ne doivent pas piéger le focus.
Les toasts ne doivent pas interrompre l'entrée du formulaire.

Les toasts sont annoncés sous forme de mises à jour en direct de la région, à une urgence qui correspond variant:

Variante	Avis	Radix `type`
`default`	Polite - en attente d'une pause	`"background"`
`success`	Polite - en attente d'une pause	`"background"`
`warning`	Assertive - interrompt immédiatement	`"foreground"`
`destructive`	Assertive - interrompt immédiatement	`"foreground"`
`info`	Polite - en attente d'une pause	`"background"`

Passez un explicite type prop pour remplacer cette valeur par défaut sur un toast spécifique.

Gardez la copie courte pour que les annonces soient compréhensibles.
Ne comptez pas uniquement sur la couleur pour les messages destructeurs ou d'avertissement.
N'utilisez pas Toast comme seul endroit pour les erreurs critiques.

Règle d'accessibilité

Les toasts sont utiles quand ils sont courts. Les messages longs ou critiques doivent entrer dans la page avec Alert.

Préférez/évitezLien vers la section

Préférez

messages de confirmation courts
Un toast par action significative
chargement en ligne avant la fin du toast
Réessayer ou annuler uniquement lorsque pris en charge
Alerte pour bloquer les pannes

Éviter

Toast pour la validation sur le terrain
Cacher les erreurs de blocage dans Toast uniquement
Empiler plusieurs toasts à la fois
longs paragraphes à l'intérieur des descriptions toast
Utilisation de Toast comme centre de notification

Quand ne pas utiliser ToastLien vers la section

N'utilisez pas Toast pour:

Erreurs de blocage
Validation sur le terrain
Flux d'intégration
Centres de notification persistants
Les échecs de paiement qui bloquent la progression
Erreurs d'autorisation nécessitant une explication
messages importants que l'utilisateur doit lire avant de continuer

Utilisez plutôt Alerte, État vide, Boîte de dialogue ou un modèle dédié.

Questions courantesLien vers la section

AlerteRétroaction en ligne pour bloquer les messages et les états de produits persistants.boîte dialogueUtilisez la boîte de dialogue lorsque l'utilisateur doit confirmer ou terminer une tâche ciblée.Actions asynchroneshronesSauvegarder, réessayer, UI optimiste, annuler et rétroaction de mutation.AccessibilitéCréez des commentaires accessibles avec une sémantique claire et des annonces.