Toast

Usage

Mount one ToastProvider for the whole application. It renders the notification region, a corner of the window where toasts stack. The application owns the list of toasts. A toast closes itself after its duration, or when Dismiss, Escape or a touch swipe closes it, by calling onOpenChange(false), and the application then removes it.

Each button below adds a toast. The toasts appear in the bottom-right corner of the window, not inside the example.

type Notice = {
  id: string;
  variant: "info" | "success" | "warning" | "error";
  title: string;
  description?: string;
};
 
const [notices, setNotices] = useState<Notice[]>([]);
const removeNotice = (id: string) =>
  setNotices((current) => current.filter((notice) => notice.id !== id));
 
<ToastProvider>
  {notices.map((notice) => (
    <Toast
      key={notice.id}
      variant={notice.variant}
      title={notice.title}
      description={notice.description}
      onOpenChange={(open) => {
        if (!open) removeNotice(notice.id);
      }}
    />
  ))}
</ToastProvider>;

A toast that is open and has no onOpenChange stays on screen for good: Dismiss and the timeout both report through onOpenChange, and nothing else closes it. Leave open out, as above, and the toast is open until it is closed. Control it with open and onOpenChange when the application needs to close it itself.

Variants

variant sets the icon, the accent color and how the toast is announced: info and success are polite, warning and error interrupt a screen reader. The first four buttons in the example show the four variants.

Without a description

description is optional. A toast with only a title is the shortest notification.

Persistent

persistent disables automatic dismissal (duration: Infinity). The toast stays until someone dismisses it, so reserve it for something that needs acknowledging.

The notification region

The region stays in the corner and never outgrows the window. When the stack is taller than the window, the region scrolls inside itself, so every Dismiss can be reached; the page behind does not scroll with it. A new toast joins the end of the stack, and the region scrolls to keep it in view, without moving focus. If you have scrolled up to read an older toast, the region stays where you left it until you scroll back to the end. Press F8 to move focus to the region, then Tab through the toasts.

Text in a toast can be selected and copied, for example a request ID: a mouse drag across a toast selects its text and never dismisses it. Swiping to dismiss is for touch. With the default right swipe, or left, a vertical touch drag on a toast scrolls the region. With up or down, a vertical drag on a toast is the swipe, so a tall stack cannot be scrolled by dragging a toast; use the wheel or the keyboard, or keep a sideways swipe when stacks can outgrow the window.

A long identifier wraps inside the toast and never pushes Dismiss out of it.

Props

Accessibility

• The region is a named landmark, <label> (F8). ToastProvider's label sets the name, and is spoken before each announcement.
• Each open toast is announced once, through a hidden live region, without moving focus. error and warning interrupt a screen reader; info and success wait their turn. Set type to foreground or background to decide otherwise. The announcement reads the title, then the description.
• Icons and titles convey severity alongside color.
• The “Dismiss” button supports keyboard activation and visible focus. Escape closes the newest open toast.
• Set ToastProvider's swipeDirection to configure touch-swipe dismissal. A mouse or pen drag selects text instead. With right or left a vertical touch drag scrolls the region; with up or down it swipes the toast.

Manifest entry

<ToastProvider>
  <Toast variant="success" title="DEPLOYED" description="Build promoted to prod." open={open} onOpenChange={setOpen} />
</ToastProvider>

{
  "description": "Wraps the app and renders the notification region, a fixed corner of the window where Toast notifications stack and announce. The region never outgrows the window: a tall stack scrolls inside it, and a new notice is scrolled into view unless the reader has scrolled away from the newest.",
  "props": {
    "label": {
      "type": "string",
      "default": "Notifications",
      "description": "Names the notification region, as '<label> (F8)', F8 being the key that moves focus to it, and is spoken before each announcement. Set it for a translated or more specific name."
    },
    "swipeDirection": {
      "type": "enum",
      "values": [
        "right",
        "left",
        "up",
        "down"
      ],
      "default": "right",
      "description": "The direction a touch swipe dismisses a toast; a mouse or pen drag selects text instead. With right or left, a vertical touch drag on a toast scrolls the region; with up or down, that drag is the swipe, so the region does not scroll by dragging a toast."
    },
    "duration": {
      "type": "number",
      "description": "Milliseconds before a toast closes itself. Defaults to 5000."
    }
  },
  "slots": {
    "children": {
      "type": "Toast",
      "required": true
    }
  },
  "never_inside": [
    "ToastProvider",
    "Toast"
  ],
  "example": "<ToastProvider>\n  <Toast variant=\"success\" title=\"DEPLOYED\" description=\"Build promoted to prod.\" open={open} onOpenChange={setOpen} />\n</ToastProvider>"
}

<Toast variant="error" title="LINK LOST" description="No telemetry for 12s." open={open} onOpenChange={setOpen} />

{
  "description": "A single transient notification with a severity icon, title, optional description, and dismiss control. It closes itself after its duration or when dismissed, by calling onOpenChange(false); the application removes it.",
  "props": {
    "variant": {
      "type": "enum",
      "values": [
        "info",
        "success",
        "warning",
        "error"
      ],
      "default": "info",
      "description": "Severity. Drives the icon, the accent color and, unless type is set, how the toast is announced: error and warning interrupt a screen reader, info and success wait."
    },
    "title": {
      "type": "string",
      "required": true
    },
    "description": {
      "type": "string"
    },
    "open": {
      "type": "boolean",
      "description": "Controlled open state. A toast that is open and never closed stays on screen: pass onOpenChange and remove the toast, or clear open, when it is called."
    },
    "defaultOpen": {
      "type": "boolean",
      "default": true,
      "description": "Initial open state when open is not controlled."
    },
    "onOpenChange": {
      "type": "function",
      "description": "Called with false when the toast closes itself after its duration, or when Dismiss, Escape or a touch swipe closes it."
    },
    "type": {
      "type": "enum",
      "values": [
        "foreground",
        "background"
      ],
      "description": "How the toast is announced: foreground interrupts a screen reader, background waits. Defaults to foreground for error and warning and background for info and success."
    },
    "duration": {
      "type": "number"
    },
    "persistent": {
      "type": "boolean",
      "default": false,
      "description": "Disables automatic dismissal (duration Infinity). The toast stays until dismissed."
    }
  },
  "composable_with": [
    "ToastProvider"
  ],
  "never_inside": [
    "Toast"
  ],
  "example": "<Toast variant=\"error\" title=\"LINK LOST\" description=\"No telemetry for 12s.\" open={open} onOpenChange={setOpen} />"
}