# Toast

> Background confirmations that stack at the top, fan out on tap, swipe away up or sideways, and pause their timers while touched.

- Type: Component (feedback)
- Access: Free, open source (MIT)
- Page: https://goodui.dev/native/components/toast
- Markdown: https://goodui.dev/native/components/toast.md
- Registry item: https://goodui.dev/native/r/toast.json
- Dependencies: react-native-gesture-handler, react-native-reanimated
- Keywords: react native toast, sonner react native, snackbar, toast with undo, notification stack, expo toast

## When to use

- Confirming work that happened in the background: a backup finished, a message was archived.
- Offering Undo after a reversible action.
- Errors from background work, such as a failed sync.

## When not to use

- As the only confirmation of an action the person just took on screen: let the control confirm in place (button does).
- Messages that need a decision: use a sheet or a dialog.

## Installation

With the shadcn CLI (needs a components.json in the Expo app), then `npx expo install --fix` so native dependencies match your Expo SDK. The foundation comes along the first time.

```bash
npx shadcn@latest add https://goodui.dev/native/r/toast.json
npx expo install --fix
```

The component lands in `components/goodui-native/toast/` and imports the foundation from `components/goodui-native/foundation/` with relative paths.

### Setup

- Wrap the app in GestureHandlerRootView and ThemeProvider.
- Render <Toaster /> once inside ThemeProvider.

## Usage

```tsx
// Once, near the root (inside ThemeProvider):
import { Toaster } from "@/components/goodui-native/toast/toast";
<Toaster />

// Anywhere:
import { toast } from "@/components/goodui-native/toast/toast";
toast.success("Backup complete", { description: "2,481 photos are safe in the cloud." });
toast("Message archived", { action: { label: "Undo", onPress: restore } });
toast.error("Couldn't sync", { description: "We'll retry when you reconnect." });
```

## API reference

### Toaster

`import { Toaster } from "@/components/goodui-native/toast/toast";`

No props.

### toast

`import { toast } from "@/components/goodui-native/toast/toast";`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `description` | `string` | – | Second line under the title. Up to three lines show. |
| `duration` | `number` | – | Milliseconds before it leaves on its own. `Infinity` keeps it until dismissed. Default 4000. |
| `action` | `{ label: string; onPress: () => void; haptic?: HapticName \| false }` | – | One short action, such as Undo. Pressing it also dismisses the toast. Its cue is `tap` unless `haptic` names another (`undo` for Undo). |
| `icon` | `ReactNode` | – | Replaces the default icon (a check for success, an alert for errors). |

## Accessibility

- Every toast is announced when it appears; the viewport is a polite live region on Android.
- Each toast is an alert with its title and description as the label; the action is a separate button.

## Motion

- New toasts drop in from the top on the smooth spring; older ones scale down and peek out below.
- Tapping the stack fans it out; it collapses again when one toast is left.
- Swipes follow the finger: up and sideways dismiss with velocity, down resists.
- Reduced motion: toasts fade in and out without travel.

## Haptics

- notify when a toast appears, error for an error toast
- tap when an action is pressed (action.haptic names another cue, such as undo)

## Performance

- A module-level store with useSyncExternalStore; only the Toaster re-renders.

## Notes for AI

- Render <Toaster /> exactly once, inside ThemeProvider. Call toast() from anywhere, including outside React.
- Keep titles short; put detail in description. At most one action.
- Use duration: Infinity for toasts that must stay until dismissed.

## Related

- [Button](https://goodui.dev/native/components/button.md): A press-responsive button with haptics that runs async actions on its own: it gathers into a spinner, then opens into a success or error state.
- [Swipe actions](https://goodui.dev/native/components/swipe-actions.md): Row actions that unfold with the finger; a long swipe lets the edge action take over and run, and destructive actions collapse the row before it leaves.

## Guidance for AI tools

Toast: Background confirmations that stack at the top, fan out on tap, swipe away up or sideways, and pause their timers while touched. Use only the documented props. Keep accessibility, reduced motion and both color schemes intact when adapting it.

Full library index: https://goodui.dev/native/llms.txt