Kobalte.v0.13.4
GitHub

Toast

A succinct message that is displayed temporarily.

Import

ts
import { Toast, toaster } from "@kobalte/core/toast";
// or
import { Root, toaster, ... } from "@kobalte/core/toast";
// or (deprecated)
import { Toast, toaster } from "@kobalte/core";
ts
import { Toast, toaster } from "@kobalte/core/toast";
// or
import { Root, toaster, ... } from "@kobalte/core/toast";
// or (deprecated)
import { Toast, toaster } from "@kobalte/core";

Features

  • Automatically closes.
  • Pauses closing on hover, focus and window blur.
  • Supports hotkey to jump to toast region.
  • Supports closing via swipe gesture.
  • Exposes CSS variables for swipe gesture animations.
  • Limit the number of visible toasts.
  • Manage promises within toast.
  • Can remove or update toast programmatically.
  • Multiple toast regions.

Anatomy

The toast region consists of:

  • Toast.Region: The fixed area where toasts appear. Users can jump to the viewport by pressing a hotkey.
  • Toast.List: The list containing all rendered toasts.
tsx
<Toast.Region>
	<Toast.List />
</Toast.Region>
tsx
<Toast.Region>
	<Toast.List />
</Toast.Region>

The toast consists of:

  • Toast: The root container for a toast.
  • Toast.CloseButton: The button that closes the toast.
  • Toast.Title: An accessible title to be announced when the toast is opened.
  • Toast.Description: An optional accessible description to be announced when the toast is opened.
  • Toast.ProgressTrack: The component that visually represents the lifetime of the toast.
  • Toast.ProgressFill: The component that visually represents the remaining lifetime of the toast.
tsx
<Toast>
	<Toast.CloseButton />
	<Toast.Title />
	<Toast.Description />
	<Toast.ProgressTrack>
		<Toast.ProgressFill />
	</Toast.ProgressTrack>
</Toast>
tsx
<Toast>
	<Toast.CloseButton />
	<Toast.Title />
	<Toast.Description />
	<Toast.ProgressTrack>
		<Toast.ProgressFill />
	</Toast.ProgressTrack>
</Toast>

Example

Usage

Showing a toast

To create a toast, use the toaster.show() method and pass the generated toastId to Toast.Root.

tsx
const id = toaster.show(props => <Toast toastId={props.toastId}>...</Toast>);
tsx
const id = toaster.show(props => <Toast toastId={props.toastId}>...</Toast>);

Updating a toast

The toaster.update() method can be used to update a toast by providing a toast id and the new component to render.

tsx
toaster.update(id, props => <Toast toastId={props.toastId}>...</Toast>);
tsx
toaster.update(id, props => <Toast toastId={props.toastId}>...</Toast>);

Notice that you always need to pass the toastId to Toast, because it doesn't know anything about the toaster nor the toast it is supposed to represent.

Dismissing a toast

The toaster.dismiss() method can be used to dismiss a toast by providing a toast id.

tsx
toaster.dismiss(id);
tsx
toaster.dismiss(id);

Clearing the toast stack and queue

Use toaster.clear() method to dismiss all toasts.

tsx
toaster.clear();
tsx
toaster.clear();

Handling promises

The toaster API exposes a toaster.promise() method to allow you update a toast when the promise resolves or rejects.

In addition to the toastId, props will contain the following properties:

  • state: The state of the promise, can be "pending" | "fulfilled" | "rejected".
  • data: The data returned by the promise when fulfilled, if any.
  • error: The error returned by the promise when rejected, if any.
tsx
toaster.promise(promise, props => (
	<Toast toastId={props.toastId}>
		<Switch>
			<Match when={props.state === "pending"}>Loading</Match>
			<Match when={props.state === "fulfilled"}>{props.data}</Match>
			<Match when={props.state === "rejected"}>{props.error}</Match>
		</Switch>
	</Toast>
));
tsx
toaster.promise(promise, props => (
	<Toast toastId={props.toastId}>
		<Switch>
			<Match when={props.state === "pending"}>Loading</Match>
			<Match when={props.state === "fulfilled"}>{props.data}</Match>
			<Match when={props.state === "rejected"}>{props.error}</Match>
		</Switch>
	</Toast>
));

Pausing the toasts

The Toast.Region component exposes the following props to pause the toasts it contains.

  • pauseOnInteraction: prop can be used to pause the toasts close timeout when a toast is hovered or focused.
  • pauseOnPageIdle: prop can be used to pause the toasts close timeout when the document loses focus or the page is idle (e.g. switching to a new browser tab).
tsx
<Toast.Region pauseOnPageIdle pauseOnInteraction>
	<Toast.List />
</Toast.Region>
tsx
<Toast.Region pauseOnPageIdle pauseOnInteraction>
	<Toast.List />
</Toast.Region>

Limiting the number of visible toasts

Use the limit prop of the Toast.Region to limit the number of toasts visible at the same time. All toasts added after limit was reached will be added into queue and displayed when a visible toast is closed.

tsx
<Toast.Region limit={3}>
	<Toast.List />
</Toast.Region>
tsx
<Toast.Region limit={3}>
	<Toast.List />
</Toast.Region>

Progress bar fill width

We expose a CSS custom property --kb-toast-progress-fill-width which corresponds to the remaining toast lifetime (in percentage). If you are building a linear progress bar to show the toast duration, you can use it to set the width of the Toast.ProgressFill component in CSS.

css
/* style.css*/
.toast__progress-fill {
	background-color: hsl(200 98% 39%);
	border-radius: 3px;
	height: 100%;
	width: var(--kb-toast-progress-fill-width);
	transition: width 250ms linear;
}
css
/* style.css*/
.toast__progress-fill {
	background-color: hsl(200 98% 39%);
	border-radius: 3px;
	height: 100%;
	width: var(--kb-toast-progress-fill-width);
	transition: width 250ms linear;
}

Animating swipe gesture

We expose the CSS custom properties --kb-toast-swipe-move-[x|y] and --kb-toast-swipe-end-[x|y] which can be used with data-swipe="[start|move|cancel|end]" attributes to animate a swipe to close gesture.

tsx
// index.tsx
import { Toast, toaster } from "@kobalte/core/toast";
import "./style.css";
function App() {
	const showToast = () => {
		toaster.show(props => (
			<Toast toastId={props.toastId} class="toast">
				...
			</Toast>
		));
	};
	return (
		<>
			<button onClick={showToast}>Show toast</button>
			<Portal>
				<Toast.Region swipeDirection="right">
					<Toast.List />
				</Toast.Region>
			</Portal>
		</>
	);
}
tsx
// index.tsx
import { Toast, toaster } from "@kobalte/core/toast";
import "./style.css";
function App() {
	const showToast = () => {
		toaster.show(props => (
			<Toast toastId={props.toastId} class="toast">
				...
			</Toast>
		));
	};
	return (
		<>
			<button onClick={showToast}>Show toast</button>
			<Portal>
				<Toast.Region swipeDirection="right">
					<Toast.List />
				</Toast.Region>
			</Portal>
		</>
	);
}
css
/* style.css */
.toast[data-swipe="move"] {
	transform: translateX(var(--kb-toast-swipe-move-x));
}
.toast[data-swipe="cancel"] {
	transform: translateX(0);
	transition: transform 200ms ease-out;
}
.toast[data-swipe="end"] {
	animation: slideRight 100ms ease-out;
}
@keyframes slideRight {
	from {
		transform: translateX(var(--kb-toast-swipe-end-x));
	}
	to {
		transform: translateX(100%);
	}
}
css
/* style.css */
.toast[data-swipe="move"] {
	transform: translateX(var(--kb-toast-swipe-move-x));
}
.toast[data-swipe="cancel"] {
	transform: translateX(0);
	transition: transform 200ms ease-out;
}
.toast[data-swipe="end"] {
	animation: slideRight 100ms ease-out;
}
@keyframes slideRight {
	from {
		transform: translateX(var(--kb-toast-swipe-end-x));
	}
	to {
		transform: translateX(100%);
	}
}

Abstracting the toaster API

It's common in toast libraries to have method for displaying different type of toast like success or error. This can be done in Kobalte by abstracting the toaster API like below.

tsx
// toast.tsx
import { Toast, toaster } from "@kobalte/core/toast";
import { JSX } from "solid-js/jsx-runtime";
import { Switch, Match } from "solid-js/web";
function show(message: string) {
	return toaster.show(props => (
		<Toast toastId={props.toastId} class="toast">
			{message}
		</Toast>
	));
}
function success(message: string) {
	return toaster.show(props => (
		<Toast toastId={props.toastId} class="toast toast--success">
			{message}
		</Toast>
	));
}
function error(message: string) {
	return toaster.show(props => (
		<Toast toastId={props.toastId} class="toast toast--error">
			{message}
		</Toast>
	));
}
function promise<T, U>(
	promise: Promise<T> | (() => Promise<T>),
	options: {
		loading?: JSX.Element;
		success?: (data: T) => JSX.Element;
		error?: (error: U) => JSX.Element;
	},
) {
	return toaster.promise(promise, props => (
		<Toast
			toastId={props.toastId}
			classList={{
				toast: true,
				"toast-loading": props.state === "pending",
				"toast-success": props.state === "fulfilled",
				"toast-error": props.state === "rejected",
			}}
		>
			<Switch>
				<Match when={props.state === "pending"}>{options.loading}</Match>
				<Match when={props.state === "fulfilled"}>{options.success?.(props.data)}</Match>
				<Match when={props.state === "rejected"}>{options.error?.(props.error)}</Match>
			</Switch>
		</Toast>
	));
}
function custom(jsx: () => JSX.Element) {
	return toaster.show(props => <Toast toastId={props.toastId}>{jsx}</Toast>);
}
function dismiss(id: number) {
	return toaster.dismiss(id);
}
export const toast = {
	show,
	success,
	error,
	promise,
	custom,
	dismiss,
};
tsx
// toast.tsx
import { Toast, toaster } from "@kobalte/core/toast";
import { JSX } from "solid-js/jsx-runtime";
import { Switch, Match } from "solid-js/web";
function show(message: string) {
	return toaster.show(props => (
		<Toast toastId={props.toastId} class="toast">
			{message}
		</Toast>
	));
}
function success(message: string) {
	return toaster.show(props => (
		<Toast toastId={props.toastId} class="toast toast--success">
			{message}
		</Toast>
	));
}
function error(message: string) {
	return toaster.show(props => (
		<Toast toastId={props.toastId} class="toast toast--error">
			{message}
		</Toast>
	));
}
function promise<T, U>(
	promise: Promise<T> | (() => Promise<T>),
	options: {
		loading?: JSX.Element;
		success?: (data: T) => JSX.Element;
		error?: (error: U) => JSX.Element;
	},
) {
	return toaster.promise(promise, props => (
		<Toast
			toastId={props.toastId}
			classList={{
				toast: true,
				"toast-loading": props.state === "pending",
				"toast-success": props.state === "fulfilled",
				"toast-error": props.state === "rejected",
			}}
		>
			<Switch>
				<Match when={props.state === "pending"}>{options.loading}</Match>
				<Match when={props.state === "fulfilled"}>{options.success?.(props.data)}</Match>
				<Match when={props.state === "rejected"}>{options.error?.(props.error)}</Match>
			</Switch>
		</Toast>
	));
}
function custom(jsx: () => JSX.Element) {
	return toaster.show(props => <Toast toastId={props.toastId}>{jsx}</Toast>);
}
function dismiss(id: number) {
	return toaster.dismiss(id);
}
export const toast = {
	show,
	success,
	error,
	promise,
	custom,
	dismiss,
};

Then inside your application, use your own toast API:

tsx
// App.tsx
import { toast } from "./toast";
function App() {
	const showToast = () => {
		toast.success("Event has been created");
	};
	return (
		<>
			<button onClick={showToast}>Show toast</button>
			<Portal>
				<Toast.Region>
					<Toast.List />
				</Toast.Region>
			</Portal>
		</>
	);
}
tsx
// App.tsx
import { toast } from "./toast";
function App() {
	const showToast = () => {
		toast.success("Event has been created");
	};
	return (
		<>
			<button onClick={showToast}>Show toast</button>
			<Portal>
				<Toast.Region>
					<Toast.List />
				</Toast.Region>
			</Portal>
		</>
	);
}

Multiple regions

The region option in toaster.show() allows you to display toast in multiple regions at the same time. Not providing a region uses the default one.

tsx
toaster.show(props => <Toast toastId={props.toastId}>...</Toast>, {
	region: "custom-region-id",
});
tsx
toaster.show(props => <Toast toastId={props.toastId}>...</Toast>, {
	region: "custom-region-id",
});

Inside your application, use add your custom region:

tsx
<Portal>
	{/* Default region */}
	<Toast.Region>
		<Toast.List />
	</Toast.Region>
	<Toast.Region regionId="custom-region-id">
		<Toast.List />
	</Toast.Region>
</Portal>
tsx
<Portal>
	{/* Default region */}
	<Toast.Region>
		<Toast.List />
	</Toast.Region>
	<Toast.Region regionId="custom-region-id">
		<Toast.List />
	</Toast.Region>
</Portal>

API reference

toaster

MethodDescription
show(toastComponent: ToastComponent, options?: ShowToastOptions) => number
Adds a new toast to the visible toasts or queue depending on current state, region and limit, and return the id of the created toast.
update(id: number, toastComponent: ToastComponent) => void
Update the toast of the given id with a new rendered component.
promise(promise: Promise<T> | (() => Promise<T>), toastComponent: ToastPromiseComponent<T, U>, options?: ShowToastOptions) => number
Adds a new promise-based toast to the visible toasts or queue depending on current state and limit, and return the id of the created toast.
dismiss(id: number) => void
Removes toast with given id from visible toasts and queue.
clear() => void
Removes all toasts from visible toasts and queue.

Toast.Region

PropDescription
aria-labelstring
default: "Notifications ({hotkey})"
A label for the toast region to provide context for screen reader users when navigating page landmarks. Can contain a {hotkey} placeholder which will be replaced for you.
hotkeystring[]
default: alt + T
The keys to use as the keyboard shortcut that will move focus to the toast region. Use event.code value for each key from keycode.info. For meta keys, use ctrlKey, shiftKey, altKey and/or metaKey.
durationnumber
default: 5000
The time in milliseconds that should elapse before automatically closing each toast.
limitnumber
default: 3
The maximum amount of toasts that can be displayed at the same time.
swipeDirection"up" | "down" | "left" | "right"
default: "right"
The direction of the pointer swipe that should close the toast.
swipeThresholdnumber
default: 50
The distance in pixels that the swipe gesture must travel before a close is triggered.
pauseOnInteractionboolean
default: true
Whether the toasts close timeout should pause when a toast is hovered or focused.
pauseOnPageIdleboolean
default: true
Whether the toasts close timeout should pause when the document loses focus or the page is idle (e.g. switching to a new browser tab).
topLayerboolean
default: true
Whether the toast region is marked as a "top layer", so that it:
- is not aria-hidden when opening an overlay.
- allows focus even outside a containing focus scope.
- doesn’t dismiss overlays when clicking on it, even though it is outside.
regionIdstring
The custom id of the region used for multiple regions.
translationsToastRegionIntlTranslations
Localization strings.

Toast

Toast is equivalent to the Root import from @kobalte/core/toast (and deprecated Toast.Root).

PropDescription
toastIdnumber
The id of the toast provided by the toaster.
priority"high" | "low"
default: "high"
Control the sensitivity of the toast for accessibility purposes. For toasts that are the result of a user action, choose high. Toasts generated from background tasks should use low.
durationnumber
The time in milliseconds that should elapse before automatically closing the toast. This will override the value supplied to Toast.Region.
persistentboolean
Whether the toast should ignore duration and disappear only by a user action.
onPause() => void
Event handler called when the dismiss timer is paused. This occurs when the pointer is moved over the region or the region is focused.
onResume() => void
Event handler called when the dismiss timer is resumed. This occurs when the pointer is moved away from the region or the region is blurred.
onSwipeStart(event: SwipeEvent) => void
Event handler called when starting a swipe interaction.
onSwipeMove(event: SwipeEvent) => void
Event handler called during a swipe interaction.
onSwipeCancel(event: SwipeEvent) => void
Event handler called when a swipe interaction is cancelled.
onSwipeEnd(event: SwipeEvent) => void
Event handler called at the end of a swipe interaction.
onEscapeKeyDown(event: KeyboardEvent) => void
Event handler called when the escape key is down. It can be prevented by calling event.preventDefault.
translationsToastIntlTranslations
Localization strings.
Data attributeDescription
data-openedPresent when the toast is open.
data-closedPresent when the toast disappear.
data-swipeThe state of the swipe, can be "start" | "move" | "cancel" | "end".
data-swipe-directionThe direction of the pointer swipe that should close the toast.
CSS custom propertyDescription
--kb-toast-swipe-move-xThe offset position of the toast when horizontally swiping.
--kb-toast-swipe-move-yThe offset position of the toast when vertically swiping.
--kb-toast-swipe-end-xThe offset end position of the toast after horizontally swiping.
--kb-toast-swipe-end-yThe offset end position of the toast after vertically swiping.

Rendered elements

ComponentDefault rendered element
Toastli
Toast.CloseButtonbutton
Toast.Titlediv
Toast.Descriptiondiv
Toast.ProgressTrackdiv
Toast.ProgressFilldiv
Toast.Regiondiv
Toast.Listol

Accessibility

Keyboard Interactions

KeyDescription
Alt + TFocuses toasts region.
TabMoves focus to the next focusable element.
Shift + TabMoves focus to the previous focusable element.
SpaceWhen focus is on a Toast.CloseButton, closes the toast.
EnterWhen focus is on a Toast.CloseButton, closes the toast.
EscWhen focus is on a toast, closes the toast.
Previous
Text Field
Next
Toggle Button