Toast
Imperative, short-lived notifications stacked at the top of the screen.
Installation
npx axiom add toastpnpm dlx axiom add toastyarn dlx axiom add toastbun x axiom add toastInstalls: react-native-reanimated, react-native-gesture-handler, react-native-safe-area-context, react-native-worklets.
Requires the success, error and info icons in your icon registry. The store, timers and swipe live in use-toast.ts. Colors come from toast.default.{default,success,error,info} in the component tokens.
Usage
Toasts are shown from code rather than declared in JSX. Mount <Toaster /> once at the root of the app.
import { Toaster, toast } from "@/components/ui/toast";
// app/_layout.tsx
<Toaster />;
// anywhere
toast.show({ title: "Profile updated" });
toast.success("Saved");API
toast.show(options)
Returns the toast id.
| Option | Type | Default | Description |
|---|---|---|---|
title | string | — | Main line. Keep it under 40 characters. |
description | string | — | Second line, in content.muted. |
type | 'default' | 'success' | 'error' | 'info' | 'loading' | 'default' | Sets the icon and the accessibility announcement. loading shows a spinner and never auto-dismisses. |
icon | IconName | per type | Replaces the type icon. |
duration | number | 4000 | Time on screen in ms. Infinity keeps it until dismissed. The timer pauses while the user touches the toast. |
id | string | generated | Passing an existing id updates that toast in place instead of adding one. |
onPress | () => void | — | Makes the toast pressable, for example to open the item it is about. |
onDismiss | () => void | — | Called when the toast leaves, by timeout or swipe. |
Shortcuts and control
| Method | Description |
|---|---|
toast.success(title, options?) / toast.error(…) / toast.info(…) | show with the type set. |
toast.loading(title, options?) | show with type: 'loading'. Update it later with the same id. |
toast.promise(promise, { loading, success, error }) | Shows loading, then success or error depending on how the promise settles. |
toast.dismiss(id?) | Hides one toast, or all of them. |
Toaster
| Prop | Type | Default | Description |
|---|---|---|---|
visibleToasts | number | 3 | Toasts shown in the stack. Older ones wait in the queue. |
offset | number | 8 | Distance below the top safe area. |
expand | 'press' | 'always' | 'press' | press stacks toasts until the user presses the stack, always lists them one under the other. |
swipeToDismiss | boolean | true | Swipe up to dismiss. |
Use cases
Confirming a background action
A short success toast for something that happened without leaving the screen.
async function copyLink() {
await Clipboard.setStringAsync(inviteUrl);
toast.success("Link copied");
}Tracking a request
toast.promise turns one toast from loading into success or error.
toast.promise(uploadPhotos(selection), {
loading: {
title: `Uploading ${selection.length} photos`,
description: "You can keep browsing.",
},
success: "Photos uploaded",
error: (e) => ({ title: "Upload failed", description: e.message }),
});Several notifications in a row
Toasts stack: the newest in front, older ones behind. Pressing the stack expands it.
socket.on("mention", (m) =>
toast.show({
title: `${m.author} mentioned you`,
description: m.excerpt,
icon: <Avatar size="sm" source={m.avatar} />,
onPress: () => router.push(m.url),
}),
);Toast or Snackbar?
| Toast | Snackbar | |
|---|---|---|
| Position | Top | Bottom |
| Visible at once | Several | One |
| Action | — | Optional |