Toast

Non-blocking feedback for product actionsLink to section

The Toast component displays short, temporary, non-blocking feedback.

Use it to:

• confirm actions
• summarize background results
• show short system messages
• provide lightweight retry or undo feedback
• acknowledge user intent without interrupting the flow

Toast is intentionally minimal in PyColors UI.

It provides structure and accessibility, not a full notification system with queues, global stores, deduping, or persistent notification history.

ImportLink to section

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

Basic usageLink to section

Toast is controlled explicitly by the page or component.

Wrap your app, route, or layout subtree with ToastProvider, then render one ToastViewport per provider scope.

"use client";

import * as React from "react";
import {
  Button,
  Toast,
  ToastProvider,
  ToastViewport,
  ToastTitle,
  ToastDescription,
} from "@pycolors/ui";

export function ToastExample() {
  const [open, setOpen] = React.useState(false);

  return (
    <ToastProvider>
      <Button onClick={() => setOpen(true)} variant="outline" size="sm">
        Trigger toast
      </Button>

      <Toast
        open={open}
        onOpenChange={setOpen}
        variant="success"
        duration={2500}
      >
        <ToastTitle>Changes saved</ToastTitle>
        <ToastDescription>
          Your settings were updated.
        </ToastDescription>
      </Toast>

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

When to use ToastLink to section

Use Toast when feedback should be noticeable but should not interrupt the user.

VariantsLink to section

Toast supports a small set of variants.

Keep variants limited to avoid turning every message into an event.

<Toast variant="default">
  <ToastTitle>Default</ToastTitle>
</Toast>

<Toast variant="success">
  <ToastTitle>Success</ToastTitle>
</Toast>

<Toast variant="warning">
  <ToastTitle>Warning</ToastTitle>
</Toast>

<Toast variant="destructive">
  <ToastTitle>Error</ToastTitle>
  <ToastDescription>
    Something went wrong.
  </ToastDescription>
</Toast>

Available variantsLink to section

With descriptionLink to section

Use ToastDescription when the title alone is not enough.

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

Keep the description short.

If the message needs more explanation, it probably belongs in an Alert, Dialog, or page section.

Usage patternsLink to section

Toast vs Alert vs DialogLink to section

Product guidanceLink to section

APILink to section

ToastLink to section

Toast extends Radix Toast root props:

React.ComponentPropsWithoutRef<typeof ToastPrimitive.Root>

ToastProviderLink to section

Wraps the area where toasts are used.

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

ToastViewportLink to section

Defines where toasts appear on screen.

Render one viewport per provider scope.

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

TypeScript typesLink to section

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

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

AccessibilityLink to section

• Toast is built on Radix Toast primitives.
• Toasts should not trap focus.
• Toasts should not interrupt form input.
• Toasts are announced as live-region updates.
• Keep copy short so announcements are understandable.
• Do not rely on color alone for destructive or warning messages.
• Do not use Toast as the only place for critical errors.

Prefer / avoidLink to section

When not to use ToastLink to section

Do not use Toast for:

• blocking errors
• field-level validation
• onboarding flows
• persistent notification centers
• payment failures that block progress
• permission errors that require explanation
• important messages the user must read before continuing

Use Alert, EmptyState, Dialog, or a dedicated pattern instead.

Common questionsLink to section

RelatedLink to section