Toast

Transient feedback for async outcomes and destructive actions. Quiet elevated surface, icon-plus-text status, and an optional undo affordance.

Included in the single kansho full pack. Components are not offered as separate installs.

Tones

Icon + text always — never colour-only status

Changes saved

Run completed

Approaching rate limit

Deployment failed

With description

Memory promoted

3 working facts moved to persistent memory for this workspace.

Static examples with actions and dismiss

Undo slot and persistent dismiss

Task archived

Secret rotation failed

This toast persists until dismissed.

Live via useToast

Fired through the Toaster provider — bottom-right viewport, max 3 visible

Task status: Active

Usage

Guidance

Fire through useToast for outcomes the operator did not sit and wait for.
Pair a reversible action with an Undo action, wired to real state.
Set duration: Infinity for danger toasts that need acknowledgement.

Don't

Use a toast for a blocking confirmation — reach for a dialog.
Stack more than a few at once; the viewport shows max 3.
Rely on colour alone — every tone carries an icon and text twin.

When to use: Async outcomes, background completions, and reversible destructive actions.
When not to: Anything the operator must act on before continuing, or long-lived status.

Accessibility

Keyboard & screen reader

Keyboard

Tab: Move focus to the Undo action or the dismiss button.
EnterSpace: Activate the focused action or dismiss button.

Announces

Danger tone renders role="alert" and interrupts the screen reader.
Other tones render role="status" with aria-live="polite".
The dismiss control carries aria-label="Dismiss".

Not supported

Auto-dismiss timer (5s default) pauses on hover or focus, not on keyboard-only reading.

Props

Toast + useToast

Component	Prop	Type	Default	Description
Toast	titlerequired	string	—	Primary line of feedback.
Toast	tone	'neutral' \| 'success' \| 'warning' \| 'danger'	'neutral'	Sets the icon and tint; danger interrupts the screen reader.
Toast	description	string	—	Optional supporting line.
Toast	action	{ label, onClick }	—	Optional single action, typically Undo.
Toast	onDismiss	() => void	—	Renders a dismiss button; the toast persists until dismissed.
Toast	icon	ReactNode	—	Override the tone's default icon.
useToast	toast	(options) => string	—	Fires a toast through the provider; returns its id.
useToast	dismiss	(id) => void	—	Dismisses a live toast by id.
ToastOptions	duration	number	5000	ms before auto-dismiss; Infinity keeps it until dismissed.

Component documentation

Toast

components/surfaces/toast.tsx

Purpose

Shows transient feedback and supplies a provider-backed queue through useToast.

Appropriate use

Use after an action when concise confirmation or recovery guidance should appear without blocking the current task.

Example

components/surfaces/toast.tsx has a representative live example in the "Tones" section on /components/toast.

States

Supports neutral, success, danger, and warning tones, title-only or described messages, optional action, dismissal, queued entry and exit, and a maximum visible stack.

API and props

Toast accepts tone, title, description, action, onDismiss, icon, and className; Toaster hosts the queue; useToast creates and dismisses toast options.

Dependencies

React, Lucide icons, Button, IconButton, and the Kansho cn utility.

Accessibility

Danger and warning feedback uses alert semantics, ordinary feedback uses a polite status region, and the dismiss action has an accessible name.

Limitations

Toasts disappear on a timer; the provider soft-caps the visible stack but persistent action toasts may exceed it, so critical instructions or durable records must also exist in page content.

Source

Source: components/surfaces/toast.tsx.

Full pack

components/surfaces/toast.tsx is documented at /components/toast and installs only through the single Kansho full pack; no individual component install is offered.