- Docs
- Toast configuration
Toast configuration
Every ToasterOptions and ToastOptions field, with its exact default and its runtime effect.
createToaster(options?), configureToaster(options?), and controller.update(options?) accept ToasterOptions. The callable toast and its variants accept ToastOptions.
Toaster options
| Option | Type | Default | Behavior |
|---|---|---|---|
id |
string |
undefined |
Legacy filter paired with a toast’s toasterId. It filters the shared global state; it does not create an independent channel. Prefer one singleton mount. |
theme |
'light' | 'dark' | 'system' |
'light' |
Sets the theme attribute on the container. system resolves to light or dark with prefers-color-scheme and follows later changes. |
position |
Position |
'bottom-right' |
Sets the viewport anchor. Corner toasts swipe toward either of their edges; centered toasts swipe vertically toward theirs. |
expand |
boolean |
false |
Keeps all stacked toasts expanded instead of expanding only during pointer interaction. |
duration |
number |
undefined |
Default per-toast duration. Resolution falls back to TOAST_LIFETIME (4000 ms); Infinity disables automatic dismissal. |
gap |
number |
GAP (14) |
Stack gap in pixels. Written to the --gap custom property. |
visibleToasts |
number |
VISIBLE_TOASTS_AMOUNT (3) |
Number of interactive, visible stack items. Other active items remain rendered with data-visible="false". |
closeButton |
boolean |
false |
Default close-button request. Loading and custom toasts never render one. A non-dismissible toast may render an inert close button, so do not combine closeButton: true with dismissible: false. |
className |
string |
undefined |
Class string on the toaster container. |
offset |
Offset |
VIEWPORT_OFFSET ('24px') per side |
Desktop viewport offsets. Missing object sides use the default. |
mobileOffset |
Offset |
MOBILE_VIEWPORT_OFFSET ('16px') per side |
Offsets used by the stylesheet on coarse pointers. Missing object sides use the default. |
dir |
'ltr' | 'rtl' | 'auto' |
detected document direction | auto resolves from the root dir attribute or the computed direction; the rendered attribute is ltr or rtl. |
richColors |
boolean |
false |
Default rich palette for typed toasts. A toast can override it. |
invert |
boolean |
false |
Inverts the normal palette. A true toaster value also applies when a toast passes invert: false; toast and toaster values are combined with a logical OR. |
unstyled |
boolean |
false |
Sets data-styled="false" for all toasts. Custom toasts are always unstyled. A toast cannot opt back into built-in styles under an unstyled toaster. |
customAriaLabel |
string |
undefined |
Preferred aria-label for the toaster container. Despite its historical name, it does not label each toast. |
containerAriaLabel |
string |
'Notifications' |
Toaster aria-label, used when customAriaLabel is absent. |
closeButtonAriaLabel |
string |
'Close toast' |
Accessible name for every generated close button. Localize this for the page language. |
style |
Record<string, string> |
undefined |
Declarations applied directly to the container’s inline style. Use CSS property names such as background or custom-property names such as --normal-bg; this is not a stylesheet object. --width can override the default. Measured --gap and --front-toast-height remain renderer-owned; use the numeric gap option. |
hotkey |
string[] |
['altKey', 'KeyT'] |
Keys that must all match. Modifiers accept altKey, ctrlKey, metaKey, or shiftKey and their short aliases; other entries match KeyboardEvent.code. An empty array disables it. Events from inputs, textareas, selects, and editable elements are ignored. |
controller.update() shallow-merges options. Omitted fields keep their current values. Inline declarations previously written by style are not removed merely because a later style map omits them.
Offset values
type Offset =
| number
| string
| {
top?: number | string
right?: number | string
bottom?: number | string
left?: number | string
}
Numbers become pixels. Strings such as '2rem' or 'env(safe-area-inset-bottom)' are used verbatim.
Toast options
| Option | Type | Default | Behavior |
|---|---|---|---|
id |
number | string |
generated counter starting at 1 |
Reusing an existing id updates that toast. Empty strings are not accepted as explicit ids and receive a generated number. Number 1 and string '1' remain distinct in state. |
toasterId |
string |
undefined |
Legacy filter matched by a mount’s id. All mounts still share ToastState, history, counter, and events; this is not isolation and not a recommended routing mechanism. |
description |
RenderableOrFactory |
undefined |
Secondary text. A function is evaluated during creation; stored values are rendered with textContent. |
type |
ToastType |
'normal' |
Controls icon and styling. Loading suppresses its timer and interactions. |
richColors |
boolean |
toaster value | Per-toast rich palette override. |
invert |
boolean |
false |
Inverts the normal palette for this toast. A true toaster value always wins. |
unstyled |
boolean |
false |
Removes the built-in toast presentation by setting data-styled="false". Custom content is always unstyled. |
closeButton |
boolean |
toaster value | Requests a close button, except on loading or custom content. |
dismissible |
boolean |
true |
Controls swipe, Delete and Backspace dismissal, and whether a generated close button acts. It does not prevent programmatic dismissal or auto-close. |
duration |
number |
toaster duration, then 4000 | Milliseconds before auto-close. Infinity disables the timer. Loading types never start one. |
className |
string |
undefined |
Class string on the toast element. |
descriptionClassName |
string |
undefined |
Class string on the description element. |
action |
ToastAction |
undefined |
Native trailing button. It closes the toast unless closeOnClick is false or onClick calls event.preventDefault(). |
cancel |
ToastAction |
undefined |
Native button rendered before action. closeOnClick defaults to true. |
testId |
string |
undefined |
Writes data-testid on the toast. |
onDismiss |
(toast: ToastT) => void |
undefined |
Runs once when the toast is dismissed by timer, close button, swipe, keyboard, toast.dismiss(), or destroyToaster(), even with several or no toasters mounted. |
onAutoClose |
(toast: ToastT) => void |
undefined |
Runs only when that renderer’s auto-dismiss timer expires, immediately before dismissal. |
onClick |
(event: Event) => void |
undefined |
Runs for a toast-body click, or Enter and Space while the toast element itself is focused. Button, link and form-control interactions, and loading toasts, are excluded. It does not dismiss automatically. |
Actions
interface ToastAction {
label: Renderable
onClick?: (event: Event) => void
closeOnClick?: boolean // default true
}
Use a concise action label that identifies the result, such as Undo deletion rather than Click here. Both action kinds are real button elements with type="button".
Inheritance example
import { createToaster, toast } from '@samline/notify'
createToaster({
duration: 6000,
richColors: true,
closeButton: true,
closeButtonAriaLabel: 'Dismiss notification',
hotkey: ['metaKey', 'KeyK'],
})
toast.info('Deployment started', {
duration: Infinity,
unstyled: false,
onClick: () => location.assign('/deployments'),
})
Read Accessibility before choosing short durations or persistent loading states.