# React Native Toast

> An accessible React Native toast for iOS, Android and the web: call toast() from anywhere, with success, error, warning, info, loading and promise toasts, actions, swipe to dismiss, a timer that pauses on touch, and screen reader announcements. No dependencies.

# Toast

A short message that confirms what just happened, such as a saved change or a failed upload, and goes away on its own. Mount `<Toaster />` once, then call `toast()` from anywhere: a component, a store, or an API client outside React. The API follows [sonner](https://sonner.emilkowal.ski), the toast shadcn/ui uses.

```tsx live
import { View } from 'react-native';

const save = () => new Promise((resolve) => setTimeout(() => resolve('Report.pdf'), 1500));

export default function Example() {
  return (
    <View style={{ height: 320 }}>
      <HStack gap="sm" wrap>
        <Button variant="outline" onPress={() => toast('Event created', { description: 'Friday at 10:00' })}>Default</Button>
        <Button variant="outline" onPress={() => toast.success('Changes saved')}>Success</Button>
        <Button variant="outline" onPress={() => toast.error('Payment failed', { description: 'Check your card details.' })}>Error</Button>
        <Button
          variant="outline"
          onPress={() => toast('Message archived', { action: { label: 'Undo', onPress: () => toast('Message restored') } })}
        >
          Action
        </Button>
        <Button
          variant="outline"
          onPress={() => toast.promise(save(), { loading: 'Saving…', success: (name) => `${name} saved`, error: 'Could not save' })}
        >
          Promise
        </Button>
      </HStack>
      <Toaster />
    </View>
  );
}
```

## Examples

Each example is live: edit the code and it runs.

### Undo a delete

A shared drive: Delete removes the file at once, and the toast keeps an Undo button for six seconds, which puts it back where it was.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Button, List, ListItem, Text, Toaster, toast } from 'patine-ui';

const FILES = [
  { id: 1, name: 'Q4 board deck.key', meta: '18.4 MB · Priya edited 2h ago' },
  { id: 2, name: 'Brand guidelines v3.pdf', meta: '6.1 MB · You edited yesterday' },
  { id: 3, name: 'Customer interviews.xlsx', meta: '412 KB · Marco edited Nov 12' },
];

export default function Example() {
  const [files, setFiles] = useState(FILES);
  const remove = (file: (typeof FILES)[number]) => {
    setFiles((all) => all.filter((f) => f.id !== file.id));
    toast(`Deleted “${file.name}”`, {
      toasterId: 'drive',
      duration: 6000,
      action: { label: 'Undo', onPress: () => setFiles((all) => [...all, file].sort((a, b) => a.id - b.id)) },
    });
  };
  return (
    <View style={{ height: 360, width: '100%' }}>
      <List title="Design team" footer="Deleted files stay in Trash for 30 days.">
        {files.map((file) => (
          <ListItem
            key={file.id}
            title={file.name}
            description={file.meta}
            trailing={
              <Button size="sm" variant="ghost" accessibilityLabel={`Delete ${file.name}`} onPress={() => remove(file)}>
                Delete
              </Button>
            }
          />
        ))}
      </List>
      {files.length ? null : <Text color="textSecondary">No files left. Undo is still on the toast.</Text>}
      <Toaster id="drive" />
    </View>
  );
}
```

### Setup

Render `<Toaster />` once, as the last child of your root view, so it draws over every screen. It covers the screen without blocking touches. Pass the safe area as `insets`, from `react-native-safe-area-context` or your own values, so toasts clear the notch and the home indicator.

```tsx
import { useSafeAreaInsets } from 'react-native-safe-area-context';
import { PatineProvider, Toaster } from 'patine-ui';

export default function App() {
  const insets = useSafeAreaInsets();
  return (
    <PatineProvider>
      <Navigation />
      <Toaster insets={insets} />
    </PatineProvider>
  );
}
```

Toasts come from the top on iOS, like its notifications, and from the bottom on Android and the web. Set `position` to choose.

### Types

`toast.success`, `toast.error`, `toast.warning` and `toast.info` add a status icon in the theme's colors. `toast.loading` shows a spinner and stays until you update or close it.

```tsx live
import { View } from 'react-native';
import { Button, HStack, Toaster, toast } from 'patine-ui';

const id = 'types';

export default function Example() {
  return (
    <View style={{ height: 300 }}>
      <HStack gap="sm" wrap>
        <Button variant="outline" onPress={() => toast('Event created', { toasterId: id })}>Default</Button>
        <Button variant="outline" onPress={() => toast.success('Changes saved', { toasterId: id })}>Success</Button>
        <Button variant="outline" onPress={() => toast.error('Payment failed', { description: 'Check your card details.', toasterId: id })}>Error</Button>
        <Button variant="outline" onPress={() => toast.warning('Your trial ends in 3 days', { toasterId: id })}>Warning</Button>
        <Button variant="outline" onPress={() => toast.info('A new version is available', { toasterId: id })}>Info</Button>
        <Button variant="outline" onPress={() => toast.loading('Syncing…', { toasterId: id, duration: 3000 })}>Loading</Button>
      </HStack>
      <Toaster id={id} />
    </View>
  );
}
```

Each example on this page sends its toasts to its own `<Toaster id>` with `toasterId`, so they don't show up in the others. In an app, one `<Toaster />` and plain `toast()` calls are all you need.

### Archive with Undo

`action` adds a button, such as Undo. The toast closes after it's pressed. A toast with an action stays until it's used or closed, so there's time to reach the button; set `duration` to close it on a timer anyway.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Button, List, ListItem, Text, Toaster, toast } from 'patine-ui';

const id = 'undo';
const INBOX = [
  { id: 1, from: 'Leo Martin', subject: 'Dinner on Friday?' },
  { id: 2, from: 'GitHub', subject: '[patine] New issue: Select on Android' },
  { id: 3, from: 'Ana Silva', subject: 'Q3 roadmap draft' },
];

export default function Example() {
  const [mails, setMails] = useState(INBOX);
  const archive = (mail: (typeof INBOX)[number]) => {
    setMails((m) => m.filter((x) => x.id !== mail.id));
    toast('Conversation archived', {
      toasterId: id,
      description: mail.subject,
      action: { label: 'Undo', onPress: () => setMails((m) => [...m, mail].sort((a, b) => a.id - b.id)) },
    });
  };
  return (
    <View style={{ height: 340, maxWidth: 440, width: '100%' }}>
      <List title="Inbox">
        {mails.map((mail) => (
          <ListItem
            key={mail.id}
            title={mail.from}
            description={mail.subject}
            trailing={<Button size="sm" variant="ghost" onPress={() => archive(mail)}>Archive</Button>}
          />
        ))}
      </List>
      {mails.length ? null : <Text color="textSecondary">Inbox zero 🎉</Text>}
      <Toaster id={id} />
    </View>
  );
}
```

### Sync, from loading to done

`toast.promise` shows a loading toast and turns it into a success or an error toast when the promise settles. A function message gets the result or the error.

```tsx live
import { View } from 'react-native';
import { Button, HStack, Toaster, toast } from 'patine-ui';

const id = 'promise';
let attempt = 0;
// Succeeds, then fails, then succeeds…
const upload = () =>
  new Promise<{ name: string }>((resolve, reject) =>
    setTimeout(() => (attempt++ % 2 ? reject(new Error('the server is busy')) : resolve({ name: 'beach.jpg' })), 1500)
  );

export default function Example() {
  return (
    <View style={{ height: 240 }}>
      <HStack gap="sm">
        <Button
          onPress={() =>
            toast.promise(
              upload(),
              {
                loading: 'Uploading…',
                success: (photo) => `${photo.name} uploaded`,
                error: (error) => `Upload failed: ${(error as Error).message}`,
              },
              { toasterId: id }
            )
          }
        >
          Upload photo
        </Button>
      </HStack>
      <Toaster id={id} />
    </View>
  );
}
```

To update any toast in place, send it again with the same `id`. Every call returns the id, and `toast.dismiss(id)` closes it; `toast.dismiss()` closes them all.

```tsx live
import { View } from 'react-native';
import { Button, HStack, Toaster, toast } from 'patine-ui';

const toasterId = 'update';

export default function Example() {
  const sync = () => {
    const id = toast.loading('Syncing 0 of 3 calendars…', { toasterId });
    [1, 2, 3].forEach((n) =>
      setTimeout(
        () => (n < 3 ? toast.loading(`Syncing ${n} of 3 calendars…`, { id, toasterId }) : toast.success('Calendars up to date', { id, toasterId })),
        n * 700
      )
    );
  };
  return (
    <View style={{ height: 220 }}>
      <HStack gap="sm">
        <Button onPress={sync}>Sync now</Button>
        <Button variant="outline" onPress={() => toast.dismiss()}>Dismiss all</Button>
      </HStack>
      <Toaster id={toasterId} />
    </View>
  );
}
```

### Closing

A toast closes after `duration` (4 seconds by default). The timer pauses while the toast is touched or hovered, and a sideways swipe closes it. The web shows a close button on every toast; other platforms show it on toasts that stay until they're closed. Set `closeButton` to show or hide it everywhere.

`max` toasts show at once (3 by default). A newer toast pushes the oldest out of view, and it comes back with its time left when there's room.

## Designs

- **Patine**: a card with a border and a soft shadow, centered.
- **iOS**: a rounded banner on the sheet surface, like a notification.
- **Material**: the Material 3 snackbar, dark on a light screen (light on a dark one), with a text button.
- **Web**: sonner's card, at the bottom right of a wide screen.

Press each one to compare:

```tsx live
import { View } from 'react-native';
import { Button, HStack, Toaster, toast } from 'patine-ui';

const DESIGNS = { brand: 'Brand', ios: 'iOS', material: 'Material', web: 'Web' } as const;

export default function Example() {
  return (
    <View style={{ height: 260 }}>
      <HStack gap="sm" wrap>
        {Object.entries(DESIGNS).map(([design, label]) => (
          <Button
            key={design}
            variant="outline"
            onPress={() => toast('Photo saved to Recents', { toasterId: `design-${design}`, action: { label: 'View', onPress: () => {} }, duration: 4000 })}
          >
            {label}
          </Button>
        ))}
      </HStack>
      {Object.keys(DESIGNS).map((design) => (
        <Toaster key={design} id={`design-${design}`} design={design as keyof typeof DESIGNS} position="bottom" />
      ))}
    </View>
  );
}
```

## Guidelines

**Offer Undo instead of asking first.** Act now and let people take it back.

**Don't confirm a small action with a toast.** “Are you sure?” in a toast vanishes before it's answered.

**Say what happened in a few words.** It's read aloud and gone in seconds.

**Don't put an error that needs fixing in a toast.** If people must act, keep the message on screen next to what failed.

## Accessibility

| | Behaviour |
| --- | --- |
| Role | `status` in a polite live region on the web (`alert` for errors); `announceForAccessibility` on iOS and Android. |
| Announced | Each toast is read when it appears; errors interrupt, the rest wait their turn. |
| Keyboard (web) | The action and close buttons are real buttons with keyboard focus on the web. |
| Touch target | The action and close buttons have 44pt touch targets; the close button reads "Close notification" (`closeLabel`). |
| Reduce motion | With reduce motion on, toasts appear and leave without sliding. |

- A toast with an action doesn't close on its own (WCAG 2.2.1), and the timer pauses while it's touched or hovered.
- The status icon isn't the only signal: say what happened in the message.

## API

### Toaster

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `'top' \| 'bottom'` | `'top'` on iOS, `'bottom'` elsewhere | The edge toasts stack from. |
| `offset` | `number` | theme `spacing.lg` | Space between the toasts and the edge, past the insets. |
| `insets` | `{ top?, bottom?, left?, right? }` | — | The safe area to keep clear. |
| `max` | `number` | `3` | The most toasts shown at once. |
| `duration` | `number` | `4000` | How long a toast stays, in ms, unless it sets its own. |
| `closeButton` | `boolean` | on the web, and on toasts that stay | A close button on every toast. |
| `closeLabel` | `string` | `'Close notification'` | The close button's label for screen readers. |
| `id` | `string` | — | Shows only toasts sent with this `toasterId`, for a second Toaster. |
| `style` | `StyleProp<ViewStyle>` | — | The box the toasts are laid out in. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |

### toast()

`toast(message, options)` shows a toast and returns its id. `toast.success`, `toast.error`, `toast.warning`, `toast.info` and `toast.loading` take the same arguments.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `description` | `string` | — | A second, smaller line under the message. |
| `action` | `{ label: string; onPress: () => void }` | — | A button in the toast. The toast closes after it's pressed, and stays until then. |
| `duration` | `number` | the Toaster's | How long it stays, in ms. `Infinity` keeps it until it's closed. |
| `id` | `string \| number` | a new id | Reuse an id to update that toast in place. |
| `toasterId` | `string` | — | Show it only in the `<Toaster id>` with this id. |

| Method | Description |
| --- | --- |
| `toast.dismiss(id?)` | Closes the toast with this id, or every toast. |
| `toast.promise(promise, { loading, success, error }, options?)` | A loading toast that turns into a success or an error toast. `promise` can be a function that returns one. Returns the id. |

Right to left and custom styles work the same on every component: see [Internationalization and right to left](../guides/i18n-rtl) and [Styling](../guides/styling).
