Components
Toast
A brief, self-dismissing confirmation of the reader's own action, built on Base UI Toast.
Usage
pnpm dlx shadcn@latest add @opsinjs/toast
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Toast } from "@/components/ui/toast"
import { Toast as ToastManager } from "@base-ui/react/toast"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
toast · base base · style base-lyraOpen under the product themeA save confirmation
A button pushes a "Saved" toast that stays a few seconds and then leaves. The words are fictional and name nothing measured.
toast-a-save-confirmation · base base · style base-lyraOpen under the product theme"use client"
import { Toast } from "@/components/ui/toast"
import { Toast as ToastPrimitive } from "@base-ui/react/toast"
function SaveButton() {
const manager = ToastPrimitive.useToastManager()
return (
<button
type="button"
onClick={() => manager.add({ title: "Saved" })}
className={
"inline-flex items-center justify-center rounded-opsin-md border border-border " +
"bg-card px-opsin-4 min-h-(--opsin-target-minimum,2.75rem) text-opsin-headline " +
"font-medium [color:var(--foreground)] cursor-pointer " +
"transition-colors duration-(--opsin-duration-fast) ease-opsin-standard hover:bg-state-hover " +
"focus-visible:outline-ring focus-visible:outline-[length:var(--opsin-border-focus,2px)] " +
"focus-visible:outline-offset-[var(--opsin-border-focus-offset,2px)]"
}
>
Save note
</button>
)
}
export default function ToastASaveConfirmation() {
return (
<Toast>
<SaveButton />
</Toast>
)
}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.
toast-with-an-action · base base · style base-lyraOpen under the product theme"use client"
import { Toast } from "@/components/ui/toast"
import { Toast as ToastPrimitive } from "@base-ui/react/toast"
function DeleteButton() {
const manager = ToastPrimitive.useToastManager()
return (
<button
type="button"
onClick={() => {
let id = ""
id = manager.add({
title: "Note removed",
actionProps: {
children: "Undo",
onClick: () => manager.close(id),
},
})
}}
className={
"inline-flex items-center justify-center rounded-opsin-md border border-border " +
"bg-card px-opsin-4 min-h-(--opsin-target-minimum,2.75rem) text-opsin-headline " +
"font-medium [color:var(--foreground)] cursor-pointer " +
"transition-colors duration-(--opsin-duration-fast) ease-opsin-standard hover:bg-state-hover " +
"focus-visible:outline-ring focus-visible:outline-[length:var(--opsin-border-focus,2px)] " +
"focus-visible:outline-offset-[var(--opsin-border-focus-offset,2px)]"
}
>
Remove note
</button>
)
}
export default function ToastWithAnAction() {
return (
<Toast>
<DeleteButton />
</Toast>
)
}When to use it
Use it when
- Confirming an action the reader took, such as a note saved or a reminder set, where missing it costs nothing.
- Acknowledging a background action that completed, such as a sync finishing, which the reader loses nothing by missing.
- Offering a brief optional way to reverse the action, such as an Undo the reader may take or ignore.
Do not use it when
- The message is a reading, a result, or anything about the reader's health they must not miss.Use
alert-bannerinstead. - The message needs attention now and stays until the reader has dealt with it.Use
alert-bannerinstead. - The information is a standing explanation, note or caveat that belongs on the surface while they read.Use
calloutinstead.
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
ToastListrightly emits no empty title. The live region still announces it througharia-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.
| Key | Action | Notes |
|---|---|---|
| F6 | Moves focus to the toast viewport | A Base UI global shortcut, so the stack is reachable without tabbing the page. |
| Tab | Moves between the controls in the focused toast | Two stops with an action, one without. Focus stays in the toast. |
| Shift+Tab | Moves back through the controls in the focused toast | The same stops in reverse. |
| Enter, Space | Activates the focused control | The close control or the action, both native buttons. |
| Escape | Dismisses the focused toast | So a reader never waits on the auto-dismiss timer. |
Contrast: 52 measured token pairs, 16 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
| body text on the canvas material | light | 104.7 | 17.96:1 | Pass |
| body text on the canvas material | dark | -100.5 | 18.00:1 | Pass |
| body text on the inset material | light | 98.1 | 16.32:1 | Pass |
| body text on the inset material | dark | -100.1 | 17.18:1 | Pass |
| body text on the card material | light | 104.7 | 17.96:1 | Pass |
| body text on the card material | dark | -99.6 | 16.32:1 | Pass |
| body text on the raised material | light | 104.7 | 17.96:1 | Pass |
| body text on the raised material | dark | -97.5 | 13.77:1 | Pass |
| body text on the sheet material over the darkest backdrop | light | 99.9 | 16.76:1 | Pass |
| body text on the sheet material over the darkest backdrop | dark | -99.7 | 16.47:1 | Pass |
| body text on the sheet material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the sheet material over the lightest backdrop | dark | -80.8 | 6.07:1 | Pass |
| body text on the overlay material over the darkest backdrop | light | 85.9 | 13.48:1 | Pass |
| body text on the overlay material over the darkest backdrop | dark | -99.9 | 16.77:1 | Pass |
| body text on the overlay material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the overlay material over the lightest backdrop | dark | -54.2 | 2.69:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from ToastProps in registry/bases/base/toast.tsx.
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.