---
title: "Toast"
description: "A brief, self-dismissing confirmation of the reader's own action, built on Base UI Toast."
url: "https://opsinjs.pensievelabs.org/docs/components/toast"
source: "https://opsinjs.pensievelabs.org/docs/components/toast.md"
section: "Components"
status: "shipped"
kind: "component"
category: "feedback"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["snackbar", "transient message", "notification toast"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="toast"
  status="shipped"
  questions="[
  &#x22;Whether a self-dismissing confirmation is announced in full before it leaves has been reasoned about from the Base UI roles rather than heard in a screen reader.&#x22;,
  &#x22;Whether the default five seconds is long enough for a reader who reads slowly, uses a switch device, or is partway through another task is unmeasured.&#x22;,
  &#x22;Whether the title, the description and the close control clear the text and non-text contrast floors has been argued from the roles rather than measured.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="toast" unbuilt="false" importPath="@/components/ui/toast" dependencies="[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]" />

```tsx
import { Toast } from "@/components/ui/toast"
import { Toast as ToastManager } from "@base-ui/react/toast"
```

```tsx
function SaveButton() {
  const manager = ToastManager.useToastManager()
  return (
    <button onClick={() => manager.add({ title: "Saved" })}>Save note</button>
  )
}

function Screen() {
  return (
    <Toast position="bottom-right">
      <SaveButton />
    </Toast>
  )
}
```

## Examples [#examples]

<ComponentPreview name="toast" />

### A save confirmation [#a-save-confirmation]

A button pushes a "Saved" toast that stays a few seconds and then leaves. The words are fictional and name nothing measured.

<ComponentPreview name="toast-a-save-confirmation" kind="example" align="start" />

### With an action [#with-an-action]

`actionProps` adds one quiet control beside the message, so a reader who removed a note by mistake can reverse it. Here Undo only closes the toast.

<ComponentPreview name="toast-with-an-action" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Confirming an action the reader took, such as a note saved or a reminder set, where missing it costs nothing.&#x22;,
  &#x22;Acknowledging a background action that completed, such as a sync finishing, which the reader loses nothing by missing.&#x22;,
  &#x22;Offering a brief optional way to reverse the action, such as an Undo the reader may take or ignore.&#x22;,
]"
  avoid="[
  { case: &#x22;The message is a reading, a result, or anything about the reader's health they must not miss.&#x22;, instead: &#x22;alert-banner&#x22; },
  { case: &#x22;The message needs attention now and stays until the reader has dealt with it.&#x22;, instead: &#x22;alert-banner&#x22; },
  { case: &#x22;The information is a standing explanation, note or caveat that belongs on the surface while they read.&#x22;, instead: &#x22;callout&#x22; },
]"
/>

## Accessibility [#accessibility]

Roles, names, the polite live region, pause on hover and focus, Escape and focus return
all come correctly from `@base-ui/react`. The X icon is `aria-hidden` and the close
carries a translatable `aria-label`. Colours are role tokens, type sizes are
`text-opsin-*` tokens, and the controls floor their hit area at `--opsin-target-minimum`.
There is no axe, target-size or 320px reflow failure. A toast follows a finger that
swipes it, springs back if let go early and leaves the way it was thrown. The close
control does the same job for a reader who cannot swipe. Under `prefers-reduced-motion`
its arrival is a short fade with no travel.

**Residual items.**

* A toast pushed with a description and no title yields a dialog with no accessible
  name, because `ToastList` rightly emits no empty title. The live region still
  announces it through `aria-describedby`, and the default and both examples always
  pass a title.
* Whether an appearing toast overlaps a control focused elsewhere is a product-layout
  question outside component scope.
* Contrast pairs are unmeasured, so the report below carries what was measured.

<KeyboardTable
  name="toast"
  rows="[
  {
    keys: &#x22;F6&#x22;,
    action: &#x22;Moves focus to the toast viewport&#x22;,
    notes: &#x22;A Base UI global shortcut, so the stack is reachable without tabbing the page.&#x22;,
  },
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves between the controls in the focused toast&#x22;,
    notes: &#x22;Two stops with an action, one without. Focus stays in the toast.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves back through the controls in the focused toast&#x22;,
    notes: &#x22;The same stops in reverse.&#x22;,
  },
  {
    keys: &#x22;Enter, Space&#x22;,
    action: &#x22;Activates the focused control&#x22;,
    notes: &#x22;The close control or the action, both native buttons.&#x22;,
  },
  {
    keys: &#x22;Escape&#x22;,
    action: &#x22;Dismisses the focused toast&#x22;,
    notes: &#x22;So a reader never waits on the auto-dismiss timer.&#x22;,
  },
]"
/>

<ContrastReport component="toast" />

## Props interface [#props-interface]

<PropsTable name="ToastProps" />

`position` defaults to `bottom-right`, `limit` to three and `timeout` to 5000ms. A toast swipes away from the edge it is docked to and towards its own corner, so a top-docked toast is thrown up rather than down, and a centred one either way. Passing `timeout={0}` stops every toast dismissing itself and raises a development warning, because a message that must persist is an AlertBanner or a Callout. `label` and `closeLabel` are props so they can be translated, and both default to English.
