ComponentsFeedback

Toast

Brief notifications from anywhere with toast(), including promises and actions.

Playground

toast.success("Invoice sent", {
  description: "Northwind will get it in a minute.",
});

Usage#

The same component at all four levels. Pick the one that fits your project; they share tokens, so they mix.

npm i junco @junco/tailwind

import { Toaster, toast } from "junco";

// Once, near the root of your app
<Toaster />

// Anywhere
toast("Saved");
toast.success("Invoice sent", { description: "Northwind will get it in a minute." });
toast.error("Couldn't save", { action: { label: "Retry", onClick: save } });
toast.promise(upload(), { loading: "Uploading…", success: "Uploaded", error: "Upload failed" });

Examples#

Types#

Each status has its own icon and words, so it never relies on color.

Promise#

Shows a loading toast that turns into success or error when the promise settles.

Action and update in place#

Reuse an id to update a toast instead of stacking a new one.

API reference#

`toast(title, options?)`#

Also toast.success, .error, .warning, .info, .loading, .promise and .dismiss(id?). Returns the toast id.

description: Second line of text.; ReactNode
id: Reuse an id to update a toast in place.; string | number
duration: Ms before it closes. Infinity keeps it open; loading toasts never auto-close.; number; Default: Toaster's duration
action: A button in the toast. It closes after onClick unless you call event.preventDefault().; { label, onClick }
dismissible: Whether close button, swipe and Esc can close it.; boolean; Default: true
ariaLabel: Text for screen readers when title or description aren't plain strings.; string
onDismiss / onAutoClose: Called when the user closes it, or when it times out.; (toast) => void

Prop	Type	Default
`description` Second line of text.	`ReactNode`	`–`
`id` Reuse an id to update a toast in place.	`string \| number`	`–`
`duration` Ms before it closes. Infinity keeps it open; loading toasts never auto-close.	`number`	`Toaster's duration`
`action` A button in the toast. It closes after onClick unless you call event.preventDefault().	`{ label, onClick }`	`–`
`dismissible` Whether close button, swipe and Esc can close it.	`boolean`	`true`
`ariaLabel` Text for screen readers when title or description aren't plain strings.	`string`	`–`
`onDismiss / onAutoClose` Called when the user closes it, or when it times out.	`(toast) => void`	`–`

`Toaster`#

Render once near the root of your app.

position: Where the stack sits.; "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"; Default: "bottom-right"
visibleToasts: How many show at once; older ones wait behind.; number; Default: 3
duration: Default auto-close time in ms.; number; Default: 5000
expand: Always show the full stack instead of collapsing it until hover or focus.; boolean; Default: false
closeButton: Show the × button on each toast.; boolean; Default: true
hotkey: Keys that move focus to the toasts.; string[]; Default: ["altKey", "KeyT"]
classNames: Class overrides for each part.; Partial<Record<slot, string>>

Prop	Type	Default
`position` Where the stack sits.	`"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"`	`"bottom-right"`
`visibleToasts` How many show at once; older ones wait behind.	`number`	`3`
`duration` Default auto-close time in ms.	`number`	`5000`
`expand` Always show the full stack instead of collapsing it until hover or focus.	`boolean`	`false`
`closeButton` Show the × button on each toast.	`boolean`	`true`
`hotkey` Keys that move focus to the toasts.	`string[]`	`["altKey", "KeyT"]`
`classNames` Class overrides for each part.	`Partial<Record<slot, string>>`	`–`

Accessibility#

Keyboard interactions
Key	Action
`AltT`	Moves focus to the newest toast.
`Tab`	Moves between toasts and their buttons.
`Esc`	Closes the focused toast.

New toasts are announced through live regions that stay mounted: errors assertively, everything else politely.
Timers pause while you hover or focus the stack, so there's time to read and act.
Status comes from the icon shape and the words, not color alone.
Swipe to dismiss is an extra; the × button and Esc always work.

Usage#

The same component at all four levels. Pick the one that fits your project; they share tokens, so they mix.

npm i junco @junco/tailwind

import { Toaster, toast } from "junco";

// Once, near the root of your app
<Toaster />

// Anywhere
toast("Saved");
toast.success("Invoice sent", { description: "Northwind will get it in a minute." });
toast.error("Couldn't save", { action: { label: "Retry", onClick: save } });
toast.promise(upload(), { loading: "Uploading…", success: "Uploaded", error: "Upload failed" });

Examples#

Types#

Each status has its own icon and words, so it never relies on color.

Promise#

Shows a loading toast that turns into success or error when the promise settles.

Action and update in place#

Reuse an id to update a toast instead of stacking a new one.

API reference#

`toast(title, options?)`#

Also toast.success, .error, .warning, .info, .loading, .promise and .dismiss(id?). Returns the toast id.

description: Second line of text.; ReactNode
id: Reuse an id to update a toast in place.; string | number
duration: Ms before it closes. Infinity keeps it open; loading toasts never auto-close.; number; Default: Toaster's duration
action: A button in the toast. It closes after onClick unless you call event.preventDefault().; { label, onClick }
dismissible: Whether close button, swipe and Esc can close it.; boolean; Default: true
ariaLabel: Text for screen readers when title or description aren't plain strings.; string
onDismiss / onAutoClose: Called when the user closes it, or when it times out.; (toast) => void

Prop	Type	Default
`description` Second line of text.	`ReactNode`	`–`
`id` Reuse an id to update a toast in place.	`string \| number`	`–`
`duration` Ms before it closes. Infinity keeps it open; loading toasts never auto-close.	`number`	`Toaster's duration`
`action` A button in the toast. It closes after onClick unless you call event.preventDefault().	`{ label, onClick }`	`–`
`dismissible` Whether close button, swipe and Esc can close it.	`boolean`	`true`
`ariaLabel` Text for screen readers when title or description aren't plain strings.	`string`	`–`
`onDismiss / onAutoClose` Called when the user closes it, or when it times out.	`(toast) => void`	`–`

`Toaster`#

Render once near the root of your app.

position: Where the stack sits.; "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"; Default: "bottom-right"
visibleToasts: How many show at once; older ones wait behind.; number; Default: 3
duration: Default auto-close time in ms.; number; Default: 5000
expand: Always show the full stack instead of collapsing it until hover or focus.; boolean; Default: false
closeButton: Show the × button on each toast.; boolean; Default: true
hotkey: Keys that move focus to the toasts.; string[]; Default: ["altKey", "KeyT"]
classNames: Class overrides for each part.; Partial<Record<slot, string>>

Prop	Type	Default
`position` Where the stack sits.	`"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"`	`"bottom-right"`
`visibleToasts` How many show at once; older ones wait behind.	`number`	`3`
`duration` Default auto-close time in ms.	`number`	`5000`
`expand` Always show the full stack instead of collapsing it until hover or focus.	`boolean`	`false`
`closeButton` Show the × button on each toast.	`boolean`	`true`
`hotkey` Keys that move focus to the toasts.	`string[]`	`["altKey", "KeyT"]`
`classNames` Class overrides for each part.	`Partial<Record<slot, string>>`	`–`

Accessibility#

Keyboard interactions
Key	Action
`AltT`	Moves focus to the newest toast.
`Tab`	Moves between toasts and their buttons.
`Esc`	Closes the focused toast.

New toasts are announced through live regions that stay mounted: errors assertively, everything else politely.

Timers pause while you hover or focus the stack, so there's time to read and act.

Status comes from the icon shape and the words, not color alone.

Swipe to dismiss is an extra; the × button and Esc always work.

Playground#

Usage#

Examples#

Types#

Promise#

Action and update in place#

API reference#

toast(title, options?)#

Toaster#

Accessibility#

Playground#

Usage#

Examples#

Types#

Promise#

Action and update in place#

API reference#

toast(title, options?)#

Toaster#

Accessibility#

`toast(title, options?)`#

`Toaster`#

`toast(title, options?)`#

`Toaster`#