/// Feedback

Toast

An imperative notification queue — mount PdsToastProvider, raise toasts anywhere via useToast().

import { PdsToastProvider, useToast } from "@protocore/pds";

View as Markdown

Basics

Mount a single PdsToastProvider near the app root. Any component beneath it calls useToast() and fires toast({ title, description, tone }) — no JSX to render, no open state to hold.

Tones

A tone sets the 2px left rule. The title is short and mono-uppercase (the outcome); the optional description carries the sans supporting line.

Imperative dismiss

toast() returns an id. Hold it to dismiss(id) early — announce a long job with a high duration, then close it yourself the moment the job resolves.

When to use it

Use a Toast for a *transient* reaction to a *discrete* action the user just took — "Node provisioned", "Couldn't save", "Copied". It's non-blocking, self-dismissing, and raised imperatively from an event handler.

A persistent, surface-wide condition? Use a Banner — a toast will vanish before it's read.
Feedback tied to a specific field or row? Use an InlineMessage.
Something that must be acknowledged or blocks the flow? Use a Dialog — never a toast, which can be missed entirely.

Don't put essential information or the only copy of an action in a toast; assume it can be missed.

The provider API

The queue is context-backed: useToast() returns { toast, dismiss } and throws if called outside a PdsToastProvider. Configure the provider once — duration (default 5000ms), swipeDirection, and the region label — and every toast inherits it unless it overrides duration per call. The provider owns the bottom-right viewport and the enter/exit animations; you never render a <Toast> element yourself.

Usage

Mount exactly one PdsToastProvider near the app root.
Raise toasts from event handlers for discrete, completed actions.
Keep the title to a short outcome; put detail in the description.
Hold the returned id to dismiss a long-running toast when its job ends.

Don't

Put essential or must-read information in a toast — it disappears.
Use a toast where the user must confirm or is blocked — that's a Dialog.
Nest multiple providers or render Toast internals directly.
Fire a burst of toasts for one logical action.

Accessibility

Keys	Action
`F8`	Moves focus into the toast viewport region (Radix hotkey).
`Tab`	Cycles through the focused toast's controls, including its close button.
`Escape`	Dismisses the focused toast.

Built on Radix Toast: the viewport is an `aria-live` region labelled by the provider `label` (default "Notifications"), so toasts are announced.
`success`/`info`/`neutral` toasts announce politely; the underlying region role escalates for higher-urgency content.
Each toast has a keyboard- and pointer-accessible close button (`aria-label` "Dismiss") plus swipe-to-dismiss.
Auto-dismiss timers pause on hover and focus, so keyboard and screen-reader users aren't rushed.

`PdsToastProvider` props

Prop	Type	Default	Description
`children` *	`ReactNode`	—	App subtree that can raise toasts.
`duration`	`number`	`5000`	Default auto-dismiss delay in ms for toasts that don't set their own.
`label`	`string`	`Notifications`	Accessible region label announced to assistive tech.
`swipeDirection`	`enum`	`right`	Swipe direction to dismiss.