# Introduction

> What expo-hot-toast is, what it draws on each platform, and when to use it.

expo-hot-toast shows toasts in Expo and React Native apps. You call
`toast.success('Saved')` from anywhere, and one `<Toaster />` near the root of
your app draws it.

```tsx
toast.success('Changes saved');
toast.error('Could not reach the server');
toast.promise(upload(photo), {
  loading: 'Uploading photo…',
  success: 'Photo uploaded',
  error: 'Upload failed',
});
```

## What it draws

| Platform | Surface |
|---|---|
| iOS 26 and later | Apple's Liquid Glass, through `expo-glass-effect` |
| iOS 26 with Reduce Transparency on | An opaque surface |
| iOS before 26 | An opaque surface |
| Android | A Material 3 snackbar at the bottom, in light and dark |
| Web | Frosted glass: a backdrop blur under a translucent fill |

The opaque surface is designed for its platform: a solid fill, border and
shadow. It does not imitate glass. On Android it follows Material 3's snackbar,
as Android apps' own messages do; `<Toaster preset="glass">` uses the pill
there too. See [Customising](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/customizing.md#presets). On the web, where browsers can blur what is
behind an element, toasts are frosted instead; anyone who prefers reduced
transparency gets the opaque surface there too.

## The API

The calls follow [react-hot-toast](https://react-hot-toast.com), the web
library: `toast`, `toast.success`, `toast.promise`, `<Toaster>`, `<ToastBar>`
and `useToaster` work as they do there. react-hot-toast itself renders DOM
elements, so it cannot run in a native app; this package rebuilds its API on
native views. If you know it from the web, read
[Coming from react-hot-toast](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/coming-from-react-hot-toast.md) for the
differences.

Beyond that API, it adds what a phone needs:

- **A queue.** Three toasts show per position; the rest wait their turn.
- **Gestures.** Flick a toast away like a notification; press and hold to
  pause every timer.
- **A collapsed stack**, if you want one: older toasts tuck behind the newest
  and fan out when pressed.
- **Actions and a close button**, for Undo and for toasts people need to clear.
- **A description line and rich colours** for outcomes that need more.
- **Deduplication**, so twenty identical calls show one toast.
- **Accessibility**: screen reader announcements, Reduce Motion, Reduce
  Transparency, capped font scaling and a haptic for success and error.

## Next

- [Install it](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/installation.md)
- [Show your first toast](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/quick-start.md)

---

# Installation

> Install the package and its peer dependencies, and set up the app root.

## Install the package

> [!NOTE]
> It is not on npm yet. Install it from GitHub; npm builds it after cloning,
> which takes a minute or two.

```sh
npm install github:VanitasCaesar1/expo-hot-toast
```

## Install the peer dependencies

> [!TIP]
> Building a React web app without React Native (Next.js, Vite)? Skip this
> step and follow [Web apps](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/web.md) instead.

```sh
npx expo install expo-glass-effect expo-haptics react-native-reanimated \
  react-native-worklets react-native-gesture-handler \
  react-native-safe-area-context react-native-svg
```

> [!TIP]
> Use `npx expo install` rather than `npm install`, so you get the versions
> that match your Expo SDK.

## Check the Babel plugin

**Expo:** nothing to do. `babel-preset-expo` adds the Worklets plugin
automatically when `react-native-worklets` is installed.

**React Native without Expo's preset:** add the plugin last in
`babel.config.js`:

```js title="babel.config.js"
module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: ['react-native-worklets/plugin'],
};
```

## Wrap the app root

Gestures need a `GestureHandlerRootView` at the root, and the Toaster reads
safe-area insets from a `SafeAreaProvider`. Expo Router already renders a
`SafeAreaProvider`; add the other.

```tsx title="App.tsx" {3,10}
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { Toaster } from 'expo-hot-toast';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <SafeAreaProvider>
        <Home />
        <Toaster />
      </SafeAreaProvider>
    </GestureHandlerRootView>
  );
}
```

Render `<Toaster />` once, after the rest of the app, so toasts draw on top.

## Requirements

| | |
|---|---|
| Expo SDK | 55 or later (tested on 57) |
| React Native | 0.80 or later (tested on 0.86) |
| React | 19 |
| Reanimated | 4 or later, with `react-native-worklets` |
| Liquid Glass | An app built with the iOS 26 SDK (Xcode 26 or later), running on iOS 26 |

Everything else falls back to the opaque surface, so the same build runs on
older iOS and on Android.

## Next

[Show your first toast](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/quick-start.md).

---

# Web apps

> Use the same toasts in a plain React app (Next.js, Vite) with no React Native.

`expo-hot-toast/web` is the library for React DOM apps: Next.js, Vite, Remix,
or anything else that renders with `react-dom`. It is the same `toast()` API,
store, queue, presets, rich toasts and theme tokens as the native build, drawn
with DOM and CSS in the same frosted glass. It needs no React Native, React
Native Web or Reanimated.

> [!NOTE]
> An Expo app that also runs on the web does not need this entry. The main
> `expo-hot-toast` import already works there, through React Native Web.

## Install

```sh
npm install github:VanitasCaesar1/expo-hot-toast
```

The React Native packages are optional peers, so a web app installs none of
them. The only peers it needs are `react` and `react-dom` 19: the stylesheet
is hoisted into the document head by React DOM 19, so with React DOM 18 the
toasts render unstyled.

## Add the Toaster

```tsx title="app/layout.tsx (Next.js)"
import { Toaster } from 'expo-hot-toast/web';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Toaster />
      </body>
    </html>
  );
}
```

The bundle starts with `'use client'`, which the App Router needs for a client
component. Its stylesheet comes with the Toaster as a React 19 hoisted
`<style>`; there is no CSS file to import.

## Show a toast

```tsx
import { toast } from 'expo-hot-toast/web';

toast.success('Changes saved');

const upload = toast.progress('Uploading 4 photos');
upload.set(0.4);
upload.success('4 photos uploaded');
```

Everything in [Toast API](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/toast-api.md) and [Rich toasts](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/rich-toasts.md)
works the same.

## What is different on the web

| | Native | Web |
|---|---|---|
| Surface | Liquid Glass on iOS 26, opaque elsewhere | Frosted glass (CSS backdrop blur); opaque without `backdrop-filter` or with reduced transparency |
| Default preset | Material snackbar on Android, glass pill elsewhere | Glass pill; `preset="material"` for the snackbar |
| `style` options | React Native styles | CSS: `toast('Hi', { style: { borderRadius: 8 } })` |
| `classNames` | Needs NativeWind or Uniwind | Plain `className`: Tailwind and any CSS work |
| Pausing | Press and hold | Hover, or press and hold on touch screens |
| Haptics | expo-haptics | None |
| Safe areas | From `react-native-safe-area-context` | CSS `env(safe-area-inset-*)` |
| `stacked` | Fans out while pressed | Fans out on hover |
| `blur`, `ContainerComponent` | Supported | Not needed: the web has backdrop blur, and nothing covers the page |

## Size

About 18 KB minified and gzipped, every rich toast type included. React and
React DOM are the only dependencies.

## Try it

The repository has a small Vite app with every toast type, light and dark,
and the presets:

```sh
npm run web:example
```

---

# Quick start

> Show a toast, update it in place, and follow a promise.

This assumes `<Toaster />` is mounted at the root, as in
[Installation](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/installation.md).

## Show a toast

Import `toast` anywhere: a component, a hook, a data layer. It does not need a
React context.

```tsx title="SaveButton.tsx"
import { Button } from 'react-native';
import { toast } from 'expo-hot-toast';

export function SaveButton() {
  return <Button title="Save" onPress={() => toast.success('Changes saved')} />;
}
```

## Update it in place

Every call returns the toast's id. Pass it back to change the toast instead of
adding another.

```tsx {3}
const id = toast.loading('Syncing…');
// later
toast.success('Synced', { id });
```

## Follow a promise

`toast.promise` does that for you: a loading toast that becomes the success or
error toast when the promise settles.

```tsx
await toast.promise(saveDraft(draft), {
  loading: 'Saving…',
  success: 'Draft saved',
  error: 'Could not save the draft',
});
```

It returns the original promise, so `await` still throws if the save fails.

## Add an Undo

```tsx
toast('Message archived', {
  action: { label: 'Undo', onPress: () => restore(message) },
});
```

## Where next

- [Toast types](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/toast-types.md): every kind of toast, and dismissing them.
- [Positions](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/positions.md): the bottom of the screen, several Toasters,
  toasts above modals.
- [Theming](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/theming.md): colours, radius, motion.

---

# Toast types

> Plain, success, error, info, warning, loading and custom toasts; icons; updating and dismissing.

## The seven calls

```tsx
import { toast } from 'expo-hot-toast';

toast('Message archived');                 // plain, no icon
toast.success('Changes saved');            // green check
toast.error('Could not reach the server'); // red mark
toast.info('A new version is ready');      // blue i
toast.warning('Storage almost full');      // amber triangle
toast.loading('Syncing…');                 // spinner, stays until changed
toast.custom(<OfflineBanner />);           // your element, drawn as-is
```

Each returns the toast's id, a string.

| Call | Icon | Default duration | Haptic |
|---|---|---|---|
| `toast()` | none | 4 s | none |
| `toast.success()` | check, drawn in | 2 s | light |
| `toast.error()` | circle with a mark | 4 s | firm |
| `toast.info()` | circle with an i | 4 s | none |
| `toast.warning()` | triangle with a mark | 4 s | warning |
| `toast.loading()` | spinner | until updated or dismissed | none |
| `toast.custom()` | none | 4 s | none |

The message can be a string, any element, or a function that receives the
toast and returns either.

## A description

`description` adds a second, quieter line under the message, for detail the
message does not need. Screen readers hear it after the message.

```tsx
toast.error('Could not upload photo', {
  description: 'Check your connection and try again.',
});
```

## Custom toasts

`toast.custom` draws your element with no surface, icon or padding, but it
still enters and leaves with the same motion and sits in the same queue.

```tsx
toast.custom(
  <View style={styles.banner}>
    <Text>You are offline</Text>
  </View>,
  { duration: 'infinite' },
);
```

To keep the built-in surface and change only what is inside it, use
[custom rendering](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/custom-rendering.md) instead.

## Icons

```tsx
toast.success('Saved', { icon: '💾' });                   // any element
toast('Saved', { icon: null });                           // none
toast.success('Saved', { iconTheme: { primary: '#30D158', secondary: '#fff' } });
```

`iconTheme.primary` colours the built-in glyph and the spinner.
`iconTheme.secondary` is accepted for react-hot-toast compatibility; the
built-in glyphs are single strokes and do not use it.

## Update a toast in place

Pass an existing id to replace that toast's type, message and options. It
stays where it is, and its icon pops in again if the type changed.

```tsx
const id = toast.loading('Uploading…');
toast.success('Uploaded', { id });
```

[`toast.promise`](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/promises.md) does this for you.

To change only some fields and keep the rest, including the toast's timer, use
`toast.update`:

```tsx
toast.update(id, { message: 'Almost there', description: '3 of 4 files' });
```

For progress bars, steps and other larger toasts, see
[Rich toasts](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/rich-toasts.md).

## Dismiss and remove

```tsx
toast.dismiss(id);   // play the exit, then remove
toast.dismiss();     // dismiss every toast
toast.dismissAll();  // the same
toast.remove(id);    // remove at once, with no exit
toast.removeAll();
```

Users can also swipe a toast away, tap it (on by default on Android), or use
an [action or close button](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/actions.md). To know which happened, pass
`onDismiss`:

```tsx
toast('Draft saved', {
  onDismiss: (id, reason) => analytics.track('toast_dismissed', { reason }),
});
```

`reason` is one of `'timeout'`, `'swipe'`, `'tap'`, `'close'`, `'action'`,
`'overflow'` or `'programmatic'`. The first reason wins: a toast that timed out
and was then swiped reports `'timeout'`.

---

# Promises

> One toast that follows a promise from loading to its outcome.

`toast.promise` shows a loading toast, then turns that same toast into the
success or error toast when the promise settles.

```tsx
import { toast } from 'expo-hot-toast';

await toast.promise(uploadPhoto(photo), {
  loading: 'Uploading photo…',
  success: 'Photo uploaded',
  error: 'Upload failed',
});
```

## Messages from the result

`success` receives the resolved value and `error` receives the rejection
reason. Either can return a string or an element.

```tsx
await toast.promise(saveDraft(draft), {
  loading: 'Saving…',
  success: (saved) => `Saved “${saved.title}”`,
  error: (cause) => `Could not save: ${cause instanceof Error ? cause.message : 'unknown error'}`,
});
```

Leave out `success` or `error` and the toast is dismissed instead of showing an
outcome for that case.

## Options per stage

The third argument takes options for every stage, plus `loading`, `success`
and `error` buckets that apply to one stage each.

```tsx
toast.promise(
  sync(),
  { loading: 'Syncing…', success: 'Synced', error: 'Sync failed' },
  {
    position: 'bottom-center',          // all stages
    success: { duration: 'short' },     // only the success toast
    error: { closeButton: true },       // only the error toast
  },
);
```

## A function instead of a promise

Pass a function to have `toast.promise` start the work. If the function throws
before returning a promise, that counts as a rejection.

```tsx
toast.promise(() => api.delete(item.id), {
  loading: 'Deleting…',
  success: 'Deleted',
  error: 'Could not delete',
});
```

## Return value

`toast.promise` returns the original promise, not a copy that swallows errors.
`await` resolves with the value, or throws the rejection, as it would without
the toast.

```tsx
try {
  const saved = await toast.promise(save(draft), messages);
  navigate('Draft', { id: saved.id });
} catch {
  // the error toast is already showing
}
```

---

# Rich toasts

> Progress bars, steps, expandable details, Undo countdowns, notifications, banners, HUDs and the island.

A toast can hold more than one line of text. Each kind below is one call, and
everything that moves (a filling bar, a draining ring) runs on the UI thread,
so it stays smooth while your JavaScript is busy.

## Info and warning

Two more outcome types, each with its own glyph and colour:

```tsx
toast.info('A new version is ready', { description: 'Restart the app to update.' });
toast.warning('Storage almost full', { description: '2% left on this device.' });
```

A warning plays the warning haptic; info plays none. With `richColors`, info is
blue and warning is amber.

## Progress

`toast.progress` shows a toast with a bar under its message and the percentage
at the end of the line, and returns a controller. Set the progress from 0 to 1,
then finish with a success or an error, which replaces the bar in the same
toast:

```tsx title="upload.ts"
const upload = toast.progress('Uploading 4 photos');

xhr.upload.onprogress = (e) => upload.set(e.loaded / e.total);
xhr.onload = () => upload.success('4 photos uploaded');
xhr.onerror = () => upload.error('Upload failed');
```

`set` writes straight to a shared value on the UI thread. Calling it on every
progress event re-renders nothing; the bar eases between values on its own.
Pass `'indeterminate'` while the length is unknown, and a sliver sweeps the
track instead.

For work that is already a promise, `toast.track` creates the toast, hands
your task a function to report progress with, and finishes the toast when the
promise settles:

```tsx
const file = await toast.track(
  (report) => download(url, { onProgress: report }),
  {
    loading: 'Downloading report',
    success: (file) => `Saved ${file.name}`,
    error: 'Download failed',
  },
);
```

`track` returns the task's own promise, so you still get the value or the
error.

### A ring instead of a bar

```tsx
toast.progress('Exporting video', { progressStyle: 'ring' });
```

The ring replaces the icon and fills clockwise from the top. The bar suits
toasts with a line or two of text; the ring suits short ones and the HUD.

## Steps

For work in named stages, `toast.steps` shows the current stage's name and a
bar split into one segment per stage, with "2/3" at the end of the line. The
stages already done are filled and the current one is tinted, since how far
through it the work is isn't known:

```tsx
const job = toast.steps(['Compressing video', 'Uploading', 'Processing']);

await compress();
job.next();
await upload();
job.next();
await process();
job.success('Video published');
```

`job.go(index)` jumps to a stage; `job.step` is the current one, from 0. A
screen reader hears each stage as "Uploading, step 2 of 3". Once the job has
an outcome, a late `next()` or `go()` does nothing, so the success toast is
never turned back into a stage.

## Expandable details

A chevron opens more content below the message. While it is open, the
Toaster's timers stop, so the details stay as long as someone is reading them:

```tsx
toast.error('3 photos failed to upload', {
  expandable: {
    content: 'IMG_2041.jpg, IMG_2042.jpg and IMG_2045.jpg are larger than 50 MB.',
  },
});
```

`content` can be any element. `defaultExpanded: true` opens it from the start,
and `label` changes what screen readers call the toggle (by default "Show
details" and "Hide details").

## Undo with a countdown

`countdown: true` on an action draws a ring around it that drains over the
time the toast has left, as Gmail's Undo does. It stops while the queue is
paused:

```tsx
toast('Conversation deleted', {
  duration: 6000,
  action: { label: 'Undo', countdown: true, onPress: restore },
});
```

## Cancel and confirm

`cancel` adds a quieter button before the action, for a question with two
answers:

```tsx
toast('Delete 3 photos?', {
  duration: 8000,
  cancel: { label: 'Cancel', onPress: () => {} },
  action: { label: 'Delete', color: '#FF3B30', onPress: deletePhotos },
});
```

Both buttons dismiss the toast after their `onPress`.

## Repeats

A toast with a `dedupeKey` shows once however often it is called. Each repeat
while it is on screen adds to a count on the toast, shown as ×2, ×3 and so on:

```tsx
toast.error('No connection', { dedupeKey: 'offline' });
```

## Shapes

`variant` changes a toast's shape. The calls below set it for you.

| Variant | Call | Where it goes | For |
|---|---|---|---|
| `pill` | `toast()` on iOS and the web | the Toaster's position | Short outcomes; the default with the glass preset |
| `snackbar` | `toast()` on Android | the Toaster's position, full width | The Material 3 default on Android |
| `card` | `toast.notify()` | the Toaster's position | Messages from people: a title, a body, a picture |
| `banner` | `toast.banner()` | edge to edge at the top, or the bottom for `bottom-*` positions | Lasting states: offline, maintenance |
| `hud` | `toast.hud()` | the middle of the screen | A large icon confirming one action |
| `island` | `toast.island()` | in the Dynamic Island, or just below the status bar | Short system-like events |

### Notification

```tsx
toast.notify({
  title: 'Maya Patel',
  body: 'Sent you 4 photos from the trip',
  avatar: { uri: maya.photoUrl },
  timestamp: 'now',
  onPress: () => router.push(`/chat/${maya.id}`),
});
```

`avatar` takes an image source or any element, and replaces the icon.
`onPress` makes the whole toast a button that dismisses after it runs.

### Banner

```tsx
toast.banner("You're offline", {
  type: 'warning',
  description: 'Changes will sync when you reconnect.',
  duration: 'infinite',
});
```

Banners default to `type: 'info'`. They span the screen and slide from the
edge rather than popping in.

### HUD

```tsx
toast.hud('Added to Library');                       // success by default
toast.hud('Saving', { type: 'loading' });
```

The HUD draws a large icon above the message and scales in where it is.

### Island

```tsx
toast.island('AirPods Pro connected', { type: 'success' });
```

A black capsule, in either appearance, as the island itself is always black.
On iPhones with a Dynamic Island it grows down out of the island and keeps its
content below the camera, as an expanded Live Activity does. Elsewhere it sits
just below the notch or status bar.

## Everything at once

These options combine. A toast can be a card with an avatar, a progress bar
and an action; a banner with a cancel button; a HUD with a ring. The example
app's "Rich toasts" section shows each kind above on iOS and Android.

---

# Actions and dismissing

> Undo buttons, the close button, tap and swipe to dismiss.

## An action button

`action` adds a trailing button. When it is pressed, its handler runs first,
then the toast is dismissed with reason `'action'`.

```tsx
toast('Message archived', {
  action: { label: 'Undo', onPress: () => restore(message) },
});
```

Give it its own colour with `color`; otherwise it uses the theme's
`actionColor`.

```tsx
action: { label: 'Retry', onPress: retry, color: '#FF9F0A' }
```

## A close button

`closeButton: true` adds a small × at the end of the toast. Use it on toasts
that stay up for a long time, or that people may want to clear early.

```tsx
toast('Export started. This can take a minute.', {
  duration: 'infinite',
  closeButton: true,
});
```

`closeButtonColor` tints the ×.

## Tap to dismiss

Tapping a toast dismisses it on Android, and does nothing on iOS, where toasts
are not usually tappable. Set `dismissOnTap` to choose for yourself:

```tsx
<Toaster toastOptions={{ dismissOnTap: true }} />
```

## Swipe to dismiss

Flick a toast toward its edge, the way you dismiss a notification: up for a
toast at the top of the screen, down for one at the bottom. About two thirds of
its height is enough, or a quick flick.

Or drag it to the right (left in right-to-left layouts), past 72 px, or fling
it that way. Dragging away from the edge, or the other way sideways, resists,
so a toast you push the wrong way springs back. Each drag follows the direction
it starts in.

A Material snackbar, the default on Android, is swiped sideways in either
direction instead, as Material 3 has it. `swipeDirections` picks the
directions for any toast:

```tsx
toast('Message archived', { swipeDirections: ['left', 'right', 'down'] });
```

Change the sideways distance, or turn swiping off, on the Toaster:

```tsx
<Toaster panThreshold={120} />   // farther
<Toaster panThreshold={0} />     // no swiping
```

## Press and hold to read

Pressing a toast pauses every timer in its Toaster until you let go, so a long
message does not vanish while someone is reading it. Paused time is added back
to each toast's deadline.

To pause from code, for example while a modal is open:

```tsx
<Toaster paused={modalOpen} />
```

---

# Positions

> Where toasts appear, spacing, several Toasters, and showing toasts above modals.

## Six positions

`top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center` and
`bottom-right`. Set the default on the Toaster, and override it per toast.

```tsx
<Toaster position="top-center" />

toast('Message sent', { position: 'bottom-center' });
```

Each position is its own stack with its own queue. Top stacks start below the
status bar and Dynamic Island; bottom stacks sit above the home indicator, and
rise above the keyboard while it is open.

## Spacing

```tsx
<Toaster
  offset={16}   // distance from the screen edge, added to the safe area
  gap={14}      // space between toasts in a stack
/>
```

The values shown are the defaults.

## Stack order

The newest toast sits nearest the edge: at the top of a top stack, at the
bottom of a bottom stack. `reverseOrder` puts it at the far end instead.

```tsx
<Toaster reverseOrder />
```

## A collapsed stack

`stacked` folds each stack behind its newest toast: older toasts tuck
underneath, each a little smaller, with only their edges showing. Press the
stack to fan it out; it folds back a moment after you let go.

```tsx
<Toaster stacked />
```

With a screen reader running, the stack stays fanned out, so every toast can
be read. It also stays fanned out with `reverseOrder`.

## Several Toasters

Give each Toaster an id, and send toasts to it with `toasterId`. Toasts without
one go to the Toaster whose id is `'default'`, which is what a Toaster without
a `toasterId` is.

```tsx
<Toaster />                                   // 'default'
<Toaster toasterId="editor" position="bottom-center" />

toast('Saved');                               // default Toaster
toast('Formatting applied', { toasterId: 'editor' });
```

Each Toaster has its own queue, settings and timers. Updating a toast by `id`
finds it in whichever Toaster already shows it.

## Above modals and sheets

A native modal or sheet covers everything rendered before it, toasts included.
On iOS, render the Toaster inside `FullWindowOverlay` from
`react-native-screens` to keep toasts on top:

```tsx
import { Platform } from 'react-native';
import { FullWindowOverlay } from 'react-native-screens';
import { Toaster } from 'expo-hot-toast';

<Toaster ContainerComponent={Platform.OS === 'ios' ? FullWindowOverlay : undefined} />
```

`react-native-screens` is not a dependency of this package; Expo Router and
React Navigation apps already have it. The Toaster wraps its content in its own
`GestureHandlerRootView`, which swiping needs inside a separate window.

---

# Timing and the queue

> Durations, the visible limit, what happens to extra toasts, and deduplication.

## Durations

| Type | Default |
|---|---|
| `toast()`, `toast.error()`, `toast.custom()` | 4000 ms |
| `toast.success()` | 2000 ms |
| `toast.loading()` | until it is updated or dismissed |

Set `duration` to a number of milliseconds, or to a preset:

```tsx
toast('Copied', { duration: 'short' });          // 2000 ms
toast('Link expires in 24 hours', { duration: 'long' });  // 4500 ms
toast('Reconnecting…', { duration: 'infinite' }); // until dismissed
toast('Saved', { duration: 3000 });
```

Change the defaults for a whole Toaster, for every type or one type at a time:

```tsx
<Toaster
  toastOptions={{
    duration: 5000,                 // every toast in this Toaster
    success: { duration: 'short' }, // except success toasts
  }}
/>
```

A toast's own options always win over the Toaster's.

### When the clock starts

A toast's time counts from when it appears on screen, not from when you called
`toast()`. A toast that waited in the queue gets its full duration once it
shows.

Time spent paused (pressing and holding a toast, the mouse over one on the
web, an expanded toast, or `<Toaster paused>`) is added back, for the time
the toast was on screen. The queue stays paused until every one of these has
let go. Toasts that would leave together are spread a little apart, the first
shown leaving first, so a stack clears one toast at a time rather than all on
one frame.

Leaving the app pauses the timers too, so a toast fired as someone locks their
phone is still there when they come back. After more than 30 seconds away,
toasts whose time ran out are dropped instead, since what they said is old
news.

## The visible limit

Three toasts show per position, first come, first shown. Fire five at once and
the first three show while the other two wait their turn, then move up in the
order you fired them as the first ones leave. Apart from making way for an
error (below), a toast never leaves the screen to come back later. The newest
toast showing is drawn at the front, nearest the edge.

A dismissed toast gives up its place as soon as it starts to leave, so the next
one moves up while it plays its exit. A HUD, a banner and the island are drawn
elsewhere and have places of their own, so a burst of toasts never pushes an
offline banner off the screen.

Errors, and toasts with `important: true`, don't wait. They show at once, and
the toast that arrived last among those showing goes back to wait for them: it
plays its exit, waits with its timer paused, and returns with its full time.

```tsx
toast.error('Payment failed');                   // goes ahead of the queue
toast('Card expires soon', { important: true }); // so does this
```

A toast that never times out (a loading toast, `toast.progress()`) holds its
place until you update or dismiss it, so three uploads at once leave others
waiting until one of them ends.

```tsx
<Toaster visibleToasts={5} />
```

## When the queue is full

Up to `maxPending` toasts (10 by default) wait beyond the visible ones at each
position. Past that, one at that position is dropped: it plays its exit and
reports the reason `'overflow'` to its `onDismiss`. `dropPolicy` picks which
one: `'oldest'`, the default, drops the toast that has been there longest,
which has been on screen, so the queue keeps moving and nothing unseen is
lost; `'newest'` drops the latest arrival. With `maxPending={0}` and
`visibleToasts={1}`, the default makes each new toast replace the one showing,
like an Android snackbar.

```tsx
<Toaster
  maxPending={10}
  dropPolicy="oldest" // or 'newest'
/>
```

## Deduplication

Give toasts a `dedupeKey`. A call whose key matches a toast already on screen,
within `dedupeWindowMs` (1000 ms by default) of the last such call, returns
that toast's id instead of adding a second one. The toast shows the count (×3)
and starts its time over, so it stays up for its full duration after the last
repeat.

```tsx
function onSaveError() {
  toast.error('Could not save', { dedupeKey: 'save-error' });
}
```

Call that from a retry loop and one toast shows, not twenty. Because the call
returns the existing id, you can also update the toast you already have:

```tsx
const id = toast('Saving draft…', { dedupeKey: 'draft', dedupeWindowMs: 3000 });
toast.success('Draft saved', { id });
```

A key whose toast has already been dismissed starts a new toast.

## After a toast is dismissed

A dismissed toast stays mounted for its exit animation, then is removed.
`removeDelay` changes how long that is; the default is the exit duration
(400 ms). A shorter value cuts the exit short.

---

# Theming

> Colours, shape, type and motion; light and dark; glass settings; tokens outside React.

Toasts are styled through tokens: named values such as `radius`, `color` and
`motion.enter`. Pass the ones you want to change; the rest keep their
defaults. [Theme tokens](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/theme-tokens.md) lists every token.

## For every toast

```tsx
<Toaster
  theme={{
    radius: 14,
    fontSize: 16,
    actionColor: '#FF9500',
    motion: { enter: 300 },
  }}
/>
```

`motion` merges key by key, so changing `enter` keeps every other duration and
curve.

## For one toast

```tsx
toast.error('Payment declined', {
  theme: { color: '#FF453A' },
  style: { borderWidth: 1, borderColor: '#FF453A' },
  textStyle: { fontWeight: '600' },
});
```

`theme` overrides tokens for that toast. `style`, `textStyle` and `iconStyle`
are React Native styles for the toast, its message and its icon, applied
after the tokens.

## Rich colours

`richColors` gives success, error, info and warning toasts an outcome colour:
a green, red, blue or amber surface, border and text on the opaque surface, and
a matching tint on Liquid Glass. Blank, loading and custom toasts are
unchanged.

```tsx
toast.success('Payment received', { richColors: true });

<Toaster toastOptions={{ richColors: true }} />   // every toast with an outcome
```

The colours are the `rich` tokens, in light and dark; see
[Theme tokens](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/theme-tokens.md#rich-colours).

## Light and dark

Toasts follow the system appearance: light tokens in light mode, dark tokens
in dark mode. If your app sets its own appearance, tell the Toaster, or dark
text can end up on a dark surface:

```tsx
<Toaster colorScheme="dark" />
```

Your `theme` overrides apply on top of whichever set is active.

## Glass

On iOS 26 the toast surface is Liquid Glass. Turn it off for a Toaster or a
single toast, and the opaque surface draws instead:

```tsx
<Toaster glass={false} />
toast('Offline', { glass: false });
```

Or configure it:

```tsx
<Toaster
  glass={{
    style: 'clear',          // 'regular' (default) or 'clear'
    tintColor: '#0A84FF33',
    interactive: true,       // the glass reacts to touch
    containerize: true,      // neighbouring toasts blend (default)
  }}
/>
```

The opaque surface uses `fallbackBackground`, `border`, `borderWidth` and the
shadow tokens. People with Reduce Transparency on always get it.

On the web, `glass` draws frosted glass instead of Liquid Glass. It fills with
`background`, lays any `tintColor` over it, blurs the page behind by
`frostBlur` and saturates it by `frostSaturation`, and lights the rim with
`frostHighlight`:

```tsx
<Toaster theme={{ frostBlur: 28, background: 'rgba(28,28,30,0.5)' }} />
```

## Tokens outside React

`resolveTheme` returns the full token set for a scheme, for use in a style
sheet or a test:

```tsx
import { resolveTheme } from 'expo-hot-toast';

const tokens = resolveTheme({ colorScheme: 'dark', theme: { radius: 14 } });
```

`toastCssVars` turns tokens into CSS custom properties, for styling systems
such as NativeWind or Unistyles:

```tsx
import { toastCssVars, resolveTheme } from 'expo-hot-toast';

const vars = toastCssVars(resolveTheme({ colorScheme: 'light' }));
```

---

# Customising

> Presets, animations, icons, styling each part, NativeWind, unstyled toasts, fonts, haptics, and matching your app's theme.

Toasts should look right in your app without any setup, and match it closely
with a little. This page goes from the broadest change to the finest.
[Theming](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/theming.md) covers the tokens themselves.

## Presets

A preset is the look a Toaster starts from:

```tsx
<Toaster preset="auto" />       // the default
<Toaster preset="glass" />      // the pill everywhere
<Toaster preset="material" />   // the Material 3 snackbar everywhere
```

`auto` gives each platform its own convention: on Android, a Material 3
snackbar (full width less a margin, 12dp corners, the inverse surface, rising
from the bottom); on iOS and the web, the glass pill at the top. `theme` is laid
over the preset, so you only override what differs.

With the Material preset the default position is `bottom-center`. Passing
`position` still wins.

## Animation

```tsx
<Toaster animation="slide" />
```

| Value | Motion |
|---|---|
| `hot` | react-hot-toast's overshooting pop; the default |
| `slide` | In from the edge by its full height, no scale |
| `fade` | In place, opacity only |
| `pop` | From small to full size, in place |
| `none` | Appears and leaves at once |

Each sets [motion tokens](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/theme-tokens.md#motion), which `theme.motion` can
still adjust. With Reduce Motion on, every animation becomes a fade in place.

## Your own icons

Give each type an icon, and the close button its own, in place of the
built-in glyphs:

```tsx
import { CheckCircle, XCircle, Info, Warning, X } from 'phosphor-react-native';

<Toaster
  icons={{
    success: <CheckCircle weight="fill" color="#34C759" size={22} />,
    error: <XCircle weight="fill" color="#FF3B30" size={22} />,
    info: <Info weight="fill" color="#0A84FF" size={22} />,
    warning: <Warning weight="fill" color="#FF9F0A" size={22} />,
    close: <X size={14} />,
  }}
/>
```

Types you leave out keep the built-in glyph. A toast's own `icon` wins over
the Toaster's, and can be a function of the toast:
`icon: (t) => <StatusDot type={t.type} />`.

## Styling each part

`styles` takes a style for any part of the built-in toast:

```tsx
<Toaster
  toastOptions={{
    styles: {
      toast: { borderRadius: 12, borderWidth: 1, borderColor: '#E5E5EA' },
      title: { letterSpacing: -0.2 },
      action: { backgroundColor: '#0A84FF', borderRadius: 8 },
      actionLabel: { color: '#FFFFFF' },
      progressBar: { backgroundColor: '#34C759' },
    },
  }}
/>
```

| Part | What it is |
|---|---|
| `toast` | The surface |
| `content` | The row, or the HUD's column, inside it |
| `icon` | The icon's box |
| `title` | The message |
| `description` | The second line |
| `action`, `actionLabel` | The action button and its text |
| `cancel`, `cancelLabel` | The cancel button and its text |
| `closeButton` | The × |
| `progressTrack`, `progressBar` | The progress bar's track and fill |
| `avatar` | The picture of a notification |
| `timestamp` | The small text at the end of the first line |
| `badge` | The ×N count |
| `expanded` | The box an expandable toast opens |

Styles given in `toastOptions`, per type and per toast all apply, in that
order, so a toast can change one part and keep the rest.

## NativeWind and Uniwind

`classNames` takes a class string for the same parts, for styling libraries
that read `className` on React Native components:

```tsx
<Toaster
  toastOptions={{
    classNames: {
      toast: 'rounded-xl border border-zinc-200 dark:border-zinc-800',
      title: 'font-semibold text-zinc-900 dark:text-zinc-50',
      description: 'text-zinc-500',
      action: 'bg-blue-500 rounded-lg',
    },
  }}
/>
```

Class strings from each level are joined, not replaced. Without such a
library, `classNames` does nothing. On the web build (`expo-hot-toast/web`)
they are ordinary `className`s, so Tailwind or any CSS works as is.

In React Native an inline style beats a class, so a part given a class drops
the token styles a class would set: a `title` class replaces the title's
colour, size, weight and font tokens, and `unstyled` leaves the toast's
padding and corners to your classes. `styles` still wins over both.

Checked with Uniwind and Tailwind 4 on Android: background, border, padding,
corners and text classes all reach the toast.

## Unstyled

`unstyled` drops the built-in surface: no fill, glass, border, shadow or
padding. The toast keeps its layout, gestures, timing and accessibility, and
you draw the rest:

```tsx
<Toaster
  toastOptions={{
    unstyled: true,
    classNames: {
      toast: 'bg-white dark:bg-zinc-900 rounded-2xl px-4 py-3 shadow-lg',
      title: 'text-sm font-medium text-zinc-900 dark:text-zinc-50',
    },
  }}
/>
```

For full control over what a toast contains, see
[Custom rendering](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/custom-rendering.md).

## Fonts and lines

```tsx
<Toaster
  theme={{
    fontFamily: 'Inter-Medium',
    descriptionFontFamily: 'Inter-Regular',
    actionFontFamily: 'Inter-SemiBold',
    maxLines: 2,
    descriptionMaxLines: 4,
  }}
/>
```

On Android a custom font is usually one family per weight, so give the family
that matches `fontWeight`. `maxLines: 0` removes the limit.

With Bold Text on (iOS: Settings, Accessibility, Display & Text Size), every
weight in the toast steps up one notch, as system text does.

## Haptics

`true` plays each type's default: light for success, rigid for error, the
warning pattern for warnings, nothing for info and loading. A map picks per
type, and a toast can pick its own:

```tsx
<Toaster haptics={{ success: 'medium', error: 'error', info: 'light' }} />

toast.success('Payment sent', { haptics: 'success' });
toast('Copied', { haptics: false });
```

Android has no weighted impacts, so `light`, `medium`, `heavy`, `rigid` and
`soft` play the notification pattern for the toast's outcome there.

## Blur on Android

Android and iOS before 26 have no Liquid Glass, so toasts there draw an opaque
surface. To draw them on a blur instead, pass a blur view you already use. The
library does not depend on one:

```tsx title="App.tsx"
import { useRef } from 'react';
import { BlurTargetView, BlurView } from 'expo-blur';
import { Toaster } from 'expo-hot-toast';

export default function App() {
  const blurTarget = useRef(null);
  return (
    <>
      <BlurTargetView ref={blurTarget} style={{ flex: 1 }}>
        <Navigation />
      </BlurTargetView>
      <Toaster
        blur={{
          component: BlurView,
          props: { intensity: 40, blurMethod: 'dimezisBlurViewSdk31Plus', blurTarget },
        }}
      />
    </>
  );
}
```

On Android, expo-blur blurs what is inside a `BlurTargetView`, so wrap your
screens in one and keep the Toaster outside it. The blur fills the toast's
shape, takes the colour scheme as its `tint` unless `props` sets one, and has
the translucent `background` token over it. Reduce Transparency, and
`glass: false` on a toast, still give the opaque surface. On iOS 26 Liquid Glass
is used and the blur is ignored.

## Matching your app's theme

If your app has a theme, toasts can take their colours from it instead of
keeping a second palette in step.

From React Navigation:

```tsx
import { useTheme } from '@react-navigation/native';
import { Toaster, fromNavigationTheme } from 'expo-hot-toast';

function AppToaster() {
  return <Toaster {...fromNavigationTheme(useTheme())} />;
}
```

From a few colours of your own design system (Tamagui, Unistyles, a constants
file):

```tsx
import { Toaster, themeFromColors } from 'expo-hot-toast';

<Toaster
  theme={themeFromColors({
    background: colors.card,
    text: colors.text,
    mutedText: colors.textSecondary,   // optional: text at 70%
    accent: colors.primary,            // optional: the action colour
    border: colors.separator,          // optional: text at 12%
    radius: 14,
    fontFamily: 'Inter-Medium',
  })}
/>
```

Both return ordinary theme tokens, so you can spread more over them. With
`glass` on, Liquid Glass draws its own material over the fill; set
`glass={false}` if the toast should be exactly your surface colour.

---

# Custom rendering

> Change what a toast contains, draw it yourself, or build your own Toaster.

There are three levels, from least to most work.

## 1. Rearrange the inside, keep the surface

Pass the Toaster a function and return a `<ToastBar>`. Its child function
receives the built-in `icon`, the `message` and the toast's `description`;
arrange them, and add your own elements. The surface, gestures, timers and motion stay as they are.

```tsx
import { Pressable, Text } from 'react-native';
import { Toaster, ToastBar, toast } from 'expo-hot-toast';

<Toaster>
  {({ toast: t }) => (
    <ToastBar toast={t}>
      {({ icon, message }) => (
        <>
          {icon}
          {message}
          {t.type !== 'loading' && (
            <Pressable onPress={() => toast.dismiss(t.id)} hitSlop={8}>
              <Text>Dismiss</Text>
            </Pressable>
          )}
        </>
      )}
    </ToastBar>
  )}
</Toaster>
```

`ToastBar` reads the Toaster's theme and settings, so you do not pass them.

## 2. Draw each toast yourself

Return your own element from the Toaster's function. You get the toast and the
resolved theme; `resolveValue` turns the message into something you can render.

```tsx
import { Text, View } from 'react-native';
import { Toaster, resolveValue } from 'expo-hot-toast';

<Toaster>
  {({ toast: t, theme }) => (
    <View style={{ backgroundColor: theme.fallbackBackground, borderRadius: theme.radius, padding: 12 }}>
      <Text style={{ color: theme.color }}>{resolveValue(t.message, t)}</Text>
    </View>
  )}
</Toaster>
```

You give up the built-in surface and gestures, but keep positioning, the queue
and timers.

For a single toast with your own element, `toast.custom(<MyBanner />)` is
simpler; see [Toast types](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/toast-types.md#custom-toasts).

## 3. Build your own Toaster

`useToaster` gives you the state and leaves all the drawing to you.

```tsx
import { useToaster, resolveValue } from 'expo-hot-toast';

function MyToaster() {
  const { toasts, pending, startPause, endPause } = useToaster();

  return (
    <View pointerEvents="box-none" style={StyleSheet.absoluteFill}>
      {toasts.map((t) => (
        <Pressable key={t.id} onPressIn={startPause} onPressOut={endPause}>
          <Text>{resolveValue(t.message, t)}</Text>
        </Pressable>
      ))}
      {pending.length > 0 && <Text>+{pending.length} more</Text>}
    </View>
  );
}
```

`toasts` are the ones that should be on screen; `pending` are queued behind
them. Each toast's `visible` flag turns false when it is dismissed: play your
exit then. `startPause` and `endPause` are also returned as `handlers`, as in
react-hot-toast.

`useToaster` takes an options object: `toastOptions`, `toasterId`,
`visibleToasts`, `maxPending`, `dropPolicy`, `defaultPosition` and `paused`,
with the same meanings as the [Toaster props](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/toaster-props.md).

---

# Accessibility

> What screen readers hear, and how toasts respond to system settings.

These work without configuration.

## Screen readers

- **iOS:** each toast is announced by VoiceOver when it appears. Errors
  interrupt what VoiceOver is saying; other types wait until it finishes.
- **Android:** each toast is a live region, which TalkBack reads. Errors are
  assertive, so they interrupt; other types wait their turn.

Mark another toast as urgent with `important`. It interrupts like an error, and
it goes ahead of the [queue](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/timing-and-queue.md#the-visible-limit):

```tsx
toast('Your session expires in one minute', { important: true });
```

A `description` is announced after the message.

A toast whose message is an element, not a string, has no text to announce.
Give it one:

```tsx
toast(<RichMessage order={order} />, { accessibilityLabel: `Order ${order.id} shipped` });
```

Toasts with an action or close button expose the message and each button
separately, so VoiceOver and TalkBack can reach the buttons.

## Rich toasts

| Toast | What a screen reader hears |
|---|---|
| Progress | The message when it starts, and the outcome when it ends. The bar and percentage change too often to read, so they are hidden from it. |
| Steps | Each step with its place: "Uploading, step 2 of 3". The outcome is read on its own. |
| Repeats | The message with its count: "No connection. 3 times". Repeats do not announce again. |
| Expandable | A "Show details" button, reported as expanded or collapsed. The details are read once open. |
| Undo countdown | An "Undo" button. The draining ring is decoration. |
| Notification | Its title and body. The avatar is decoration. |

## Reduce Motion

Toasts fade in and out where they sit, with no travel or scaling, and icons
arrive already drawn: no pop and no checkmark draw-in. The stack still moves up
when a toast leaves, so the change is visible.

## Reduce Transparency

On iOS 26, toasts use the opaque surface instead of Liquid Glass. On the web,
the browser's `prefers-reduced-transparency` setting does the same for the
frosted glass.

## Text size

Toast text follows the system text size, up to twice the default. At the
larger sizes a toast takes up to six lines instead of three, so a message is
not cut short. Change the size cap with the `maxFontSizeMultiplier` token, or
remove it with `null`:

```tsx
<Toaster theme={{ maxFontSizeMultiplier: null }} />
```

## Haptics

Success, warning and error toasts play the system's notification haptic when
they appear, the pattern iOS and Android keep for the outcome of a task. Info,
loading and plain toasts play none.

Turn them off for a Toaster, or for one toast:

```tsx
<Toaster haptics={false} />
toast.success('Saved', { haptics: false });
```

## Collapsed stacks

A `stacked` Toaster hides the content of toasts tucked behind the front one.
While VoiceOver or TalkBack is running, the stack stays fanned out instead.

---

# toast()

> Every function on the toast object, with its signature.

```ts
import { toast } from 'expo-hot-toast';
// or: import toast from 'expo-hot-toast';
```

## Creating toasts

```ts
toast(message, options?): string
toast.success(message, options?): string
toast.error(message, options?): string
toast.info(message, options?): string
toast.warning(message, options?): string
toast.loading(message, options?): string
toast.custom(element, options?): string
```

| Parameter | Type |
|---|---|
| `message` | `ReactNode`, or `(toast: Toast) => ReactNode` |
| `options` | [`ToastOptions`](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/toast-options.md) |

Returns the toast's id. With an `id` in `options`, replaces that toast instead.
With a `dedupeKey` that matches a toast on screen, returns that toast's id,
adds nothing, and counts the repeat on the toast (it shows `×2`, `×3`, …).

## toast.update

```ts
toast.update(id: string, changes: Partial<ToastOptions> & { message?, type? }): void
```

Changes some fields of a toast that is showing and keeps the rest, its place
in the queue and its timer. A `duration` in `changes` restarts the timer with
the new length. Unlike `toast(…, { id })`, nothing is replaced.

## Shapes

```ts
toast.hud(message, options?: ToastOptions & { type? }): string      // default type 'success'
toast.banner(message, options?: ToastOptions & { type? }): string   // default type 'info'
toast.island(message, options?: ToastOptions & { type? }): string   // default type 'blank'
toast.notify({ title, body?, type?, ...options }): string
```

Each sets `variant` for you. See [Rich toasts](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/rich-toasts.md#shapes).

## Progress

```ts
toast.progress(message, options?): ProgressController
toast.steps(labels: string[], options?): StepsController
toast.track<T>(
  task: (report: (progress: number) => void) => Promise<T>,
  messages: { loading; success?; error? },
  options?,
): Promise<T>

interface ProgressController {
  id: string;
  set(progress: number | 'indeterminate'): void; // 0 to 1, on the UI thread
  update(changes): void;
  success(message, options?): void;
  error(message, options?): void;
  dismiss(): void;
}

interface StepsController extends Omit<ProgressController, 'set'> {
  step: number;
  next(): void;
  go(index: number): void;
}
```

`set` writes the value to the UI thread directly, so calling it many times a
second never re-renders the toast. See [Rich toasts](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/rich-toasts.md#progress).

## toast.promise

```ts
toast.promise<T>(
  promise: Promise<T> | (() => Promise<T>),
  messages: {
    loading: ReactNode;
    success?: ReactNode | ((value: T) => ReactNode);
    error?: ReactNode | ((error: unknown) => ReactNode);
  },
  options?: ToastOptions & { loading?: ToastOptions; success?: ToastOptions; error?: ToastOptions },
): Promise<T>
```

Returns the original promise. See [Promises](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/promises.md).

## Dismissing and removing

```ts
toast.dismiss(toastId?: string, toasterId?: string, reason?: DismissReason): void
toast.dismissAll(toasterId?: string, reason?: DismissReason): void
toast.remove(toastId?: string, toasterId?: string): void
toast.removeAll(toasterId?: string): void
```

`dismiss` plays the exit animation, then removes the toast. `remove` takes it
off screen at once. Without a `toastId` they apply to every toast; without a
`toasterId`, to every Toaster.

`reason` is passed to the toast's `onDismiss`. It defaults to
`'programmatic'`.

## Types

```ts
type DismissReason =
  | 'timeout' | 'swipe' | 'tap' | 'close' | 'action' | 'overflow' | 'programmatic';

type ToastType = 'blank' | 'success' | 'error' | 'info' | 'warning' | 'loading' | 'custom';

type ToastVariant = 'auto' | 'pill' | 'snackbar' | 'card' | 'banner' | 'hud' | 'island';

type SwipeDirection = 'left' | 'right' | 'up' | 'down';

type ToastHaptic =
  | 'light' | 'medium' | 'heavy' | 'rigid' | 'soft' | 'success' | 'warning' | 'error' | false;

type ToastPosition =
  | 'top-left' | 'top-center' | 'top-right'
  | 'bottom-left' | 'bottom-center' | 'bottom-right';
```

---

# Toast options

> Every option a toast accepts, with its type and default.

Pass these as the second argument to `toast()`, or as defaults in
`<Toaster toastOptions>`, where they can also be grouped by type
(`success`, `error`, `info`, `warning`, `loading`, `blank`, `custom`). A toast's own options win.

## Content

| Option | Type | Default | |
|---|---|---|---|
| `id` | `string` | generated | Reuse an id to update that toast in place |
| `description` | `ReactNode` | none | A second, quieter line under the message |
| `icon` | `ReactNode`, or `(toast) => ReactNode` | per type | Replaces the built-in icon; `null` hides it |
| `iconTheme` | `{ primary, secondary }` | per type | `primary` colours the built-in glyph and spinner |
| `action` | `{ label, onPress, color?, countdown? }` | none | A trailing button; the toast dismisses after `onPress`. `countdown: true` drains a ring around it over the time left |
| `cancel` | `{ label, onPress, color? }` | none | A quieter button before `action`, for "Cancel / Delete" pairs |
| `closeButton` | `boolean` | `false` | A trailing × button |
| `closeButtonColor` | `string` | theme `color` | Colour of the × |
| `avatar` | image source or `ReactNode` | none | A round picture in place of the icon |
| `timestamp` | `string` | none | Small text at the end of the first line ("now", "2/4") |
| `expandable` | `{ content, label?, defaultExpanded? }` | none | A toggle that shows more below; the toast pauses while open |

## Progress

| Option | Type | Default | |
|---|---|---|---|
| `progress` | `number` (0 to 1) or `'indeterminate'` | none | Shows a bar; prefer [`toast.progress`](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/rich-toasts.md#progress), which updates on the UI thread |
| `progressStyle` | `'bar'` or `'ring'` | `'bar'` | A bar along the bottom edge, or a ring around the icon |
| `progressSegments` | `number` | none | Splits the bar into steps |

## Timing and placement

| Option | Type | Default | |
|---|---|---|---|
| `duration` | `number`, `'short'`, `'long'` or `'infinite'` | 4000; success 2000; loading infinite | Milliseconds, or 2000 / 4500 / never |
| `position` | `ToastPosition` | the Toaster's | One of the six positions |
| `toasterId` | `string` | `'default'` | Which Toaster shows it |
| `dedupeKey` | `string` | none | Skip this toast if one with the same key is on screen, and count the repeat |
| `dedupeWindowMs` | `number` | `1000` | How long a key counts as on screen |
| `removeDelay` | `number` | the exit duration (400) | How long a dismissed toast stays mounted |

## Behaviour

| Option | Type | Default | |
|---|---|---|---|
| `dismissOnTap` | `boolean` | `true` on Android (except a toast with progress), `false` on iOS | Tap to dismiss |
| `onPress` | `() => void` | none | Tapping the toast calls this, then dismisses it |
| `dismissible` | `boolean` | `true` | `false` turns off swipe and tap to dismiss; a button or the timer still can |
| `swipeDirections` | `SwipeDirection[]` | toward its edge, and right (left in right-to-left layouts); left and right for a snackbar | Which ways a swipe dismisses |
| `onDismiss` | `(id, reason) => void` | none | Called once the toast has left, with why |
| `haptics` | `boolean` or `ToastHaptic` | the Toaster's | `false` for silence, or a named haptic: `'light'`, `'medium'`, `'heavy'`, `'rigid'`, `'soft'`, `'success'`, `'warning'`, `'error'` |
| `important` | `boolean` | `true` for errors | Show at once, ahead of the queue, and interrupt other announcements |
| `accessibilityLabel` | `string` | the message text | What screen readers announce |

## Appearance

| Option | Type | Default | |
|---|---|---|---|
| `variant` | `'auto'`, `'pill'`, `'snackbar'`, `'card'`, `'banner'`, `'hud'` or `'island'` | `'auto'` | The toast's shape; see [Rich toasts](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/rich-toasts.md#shapes) |
| `theme` | partial [theme tokens](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/theme-tokens.md) | none | Token overrides for this toast |
| `glass` | `boolean` or `GlassConfig` | the Toaster's | `false` draws the opaque surface |
| `richColors` | `boolean` | `false` | Tinted surface and text for success, error, info and warning toasts |
| `style` | `ViewStyle` | none | The toast surface, applied after tokens |
| `textStyle` | `TextStyle` | none | The message |
| `iconStyle` | `ViewStyle` | none | The icon's box |
| `styles` | `{ [slot]: style }` | none | A style for any part; see [Customising](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/customizing.md#styling-each-part) |
| `classNames` | `{ [slot]: string }` | none | A `className` for any part, for NativeWind or Uniwind |
| `unstyled` | `boolean` | `false` | Draw no surface, padding or shadow; bring your own through `styles` |

`closeable` still works as a deprecated name for `closeButton`.

---

# Toaster props

> Every prop the Toaster accepts, with its type and default.

```tsx
<Toaster position="top-center" visibleToasts={3} />
```

## Placement

| Prop | Type | Default | |
|---|---|---|---|
| `position` | `ToastPosition` | `'top-center'`; `'bottom-center'` with the Material preset | For toasts that do not set one |
| `offset` | `number` | `16` | Distance from the screen edge, added to the safe area |
| `gap` | `number` | `14` | Space between toasts |
| `reverseOrder` | `boolean` | `false` | Newest toast at the far end of the stack |
| `toasterId` | `string` | `'default'` | Run several independent Toasters |
| `ContainerComponent` | component | none | Render inside another component, such as `FullWindowOverlay` |
| `containerStyle` | `ViewStyle` | none | The full-screen container |

## Queue

| Prop | Type | Default | |
|---|---|---|---|
| `visibleToasts` | `number` | `3` | Toasts shown at once per position |
| `maxPending` | `number` | `10` | Toasts that wait beyond the visible ones |
| `dropPolicy` | `'oldest'` or `'newest'` | `'oldest'` | Which toast to drop when the queue is full |
| `paused` | `boolean` | `false` | Freeze every timer |
| `stacked` | `boolean` | `false` | Collapse each stack behind its newest toast; press to fan it out |

## Defaults and appearance

| Prop | Type | Default | |
|---|---|---|---|
| `preset` | `'auto'`, `'glass'` or `'material'` | `'auto'` | The look to start from: a Material 3 snackbar on Android, the glass pill elsewhere; see [Customising](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/customizing.md#presets) |
| `animation` | `'hot'`, `'slide'`, `'fade'`, `'pop'` or `'none'` | `'hot'` | How toasts come and go |
| `icons` | `{ success?, error?, info?, warning?, loading?, blank?, close? }` | none | Icons in place of the built-in glyphs |
| `blur` | `{ component, props? }` | none | A blur view, such as expo-blur's, for Android and iOS before 26; see [Customising](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/customizing.md#blur-on-android) |
| `toastOptions` | [`ToastOptions`](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/toast-options.md), plus per-type buckets | none | Defaults for every toast in this Toaster |
| `theme` | partial [theme tokens](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/theme-tokens.md) | none | Token overrides |
| `colorScheme` | `'light'` or `'dark'` | the system's | Force light or dark tokens |
| `glass` | `boolean` or `GlassConfig` | `true` | `false` draws the opaque surface everywhere |
| `panThreshold` | `number` | `72` | Sideways swipe distance that dismisses; `0` turns swiping off |
| `haptics` | `boolean`, or a map from type to `ToastHaptic` | `true` | `true` plays each type's default (success, error, warning); a map picks per type: `{ success: 'medium', info: 'light' }` |
| `announce` | `boolean` | `true` | `false` keeps screen readers from hearing this Toaster's toasts, for a preview or a demo that plays on its own |
| `children` | `({ toast, theme }) => ReactNode` | none | Draw each toast yourself; see [Custom rendering](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/custom-rendering.md) |

## GlassConfig

| Field | Type | Default | |
|---|---|---|---|
| `style` | `'regular'` or `'clear'` | `'regular'` | The Liquid Glass variant |
| `tintColor` | `string` | none | Tint over the glass |
| `interactive` | `boolean` | `false` | The glass reacts to touch |
| `containerize` | `boolean` | `true` | Put a stack in one glass container, so neighbours blend |
| `containerSpacing` | `number` | the `gap` | Distance at which neighbours blend |

`gutter` and `toastLimit` still work as deprecated names for `gap` and
`visibleToasts`.

---

# Theme tokens

> Every token, with its light and dark default.

Override any of these with `<Toaster theme>` or a toast's `theme` option. See
[Theming](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/theming.md) for how.

## Surface

| Token | Light | Dark | |
|---|---|---|---|
| `fallbackBackground` | `#FFFFFF` | `#2C2C2E` | Fill of the opaque surface |
| `background` | `rgba(255,255,255,0.72)` | `rgba(28,28,30,0.72)` | Fill of the frosted glass on the web |
| `border` | `rgba(255,255,255,0.6)` | `rgba(255,255,255,0.14)` | Border of the opaque surface and the frosted glass |
| `frostBlur` | `18` | same | Web only: backdrop blur, in px |
| `frostSaturation` | `180` | same | Web only: backdrop saturation, in percent |
| `frostHighlight` | `rgba(255,255,255,0.9)` | `rgba(255,255,255,0.3)` | Web only: light in the glass rim |
| `borderWidth` | `0` on 3x screens, else `1` | same | |
| `radius` | `22` | same | Corner radius |
| `shadowColor` | `#000000` | same | Opaque surface and frosted glass |
| `shadowOpacity` | `0.12` | `0.3` | |
| `shadowRadius` | `16` | same | |
| `shadowOffsetY` | `6` | same | |
| `elevation` | `8` | same | Android shadow |

Liquid Glass draws its own material and ignores the fill, border and shadow.

## Layout

| Token | Default | |
|---|---|---|
| `paddingVertical` | `14` | |
| `paddingHorizontal` | `18` | |
| `maxWidth` | `340` | A toast grows with its message up to this width |
| `gap` | `10` | Space between the icon, message and buttons |
| `iconSize` | `22` | |
| `fill` | `false` | `true` stretches the toast to its stack's width, as a snackbar does |

## Text

| Token | Light | Dark | |
|---|---|---|---|
| `color` | `#1c1c1e` | `#f2f2f7` | Message and spinner |
| `fontSize` | `15` | same | |
| `lineHeight` | `20` | same | |
| `fontWeight` | `'500'` | same | |
| `maxFontSizeMultiplier` | `2` | same | Cap on system text size; `null` removes it |
| `descriptionColor` | `rgba(60,60,67,0.78)` | `rgba(235,235,245,0.68)` | The description line |
| `descriptionFontSize` | `13` | same | |
| `descriptionLineHeight` | `18` | same | |
| `fontFamily` | system | same | The message's font |
| `descriptionFontFamily` | `fontFamily` | same | |
| `actionFontFamily` | `fontFamily` | same | The action and cancel labels |
| `maxLines` | `3` | same | Lines of message before it truncates; `0` for no limit |
| `descriptionMaxLines` | `3` | same | |

With Bold Text on (iOS), every weight steps up one notch, as system text does.

## Buttons

| Token | Light | Dark | |
|---|---|---|---|
| `actionColor` | `#0A84FF` | same | Action button label |
| `actionPaddingHorizontal` | `12` | same | |
| `closeButtonBackground` | `rgba(0,0,0,0.07)` | `rgba(255,255,255,0.18)` | Circle behind the × |

## Rich colours

Used by toasts with `richColors`. Override one field without losing the rest:
`theme={{ rich: { error: { tint: 'rgba(255,0,0,0.3)' } } }}`.

| Token | Light | Dark | |
|---|---|---|---|
| `rich.success.background` | `#ECFDF3` | `#032313` | Opaque surface |
| `rich.success.border` | `#BFF5D6` | `#0B4425` | |
| `rich.success.color` | `#00702A` | `#5FE39A` | Message and description |
| `rich.success.tint` | `rgba(52,199,89,0.22)` | `rgba(48,209,88,0.26)` | Tint over Liquid Glass and frosted glass |
| `rich.error.background` | `#FFF0F0` | `#2E0809` | |
| `rich.error.border` | `#FFD9DA` | `#561317` | |
| `rich.error.color` | `#C8000F` | `#FF8F92` | |
| `rich.error.tint` | `rgba(255,59,48,0.22)` | `rgba(255,69,58,0.26)` | |
| `rich.info.background` | `#EEF6FF` | `#06203D` | |
| `rich.info.border` | `#C9E2FF` | `#0E3A6B` | |
| `rich.info.color` | `#0058C4` | `#7DB9FF` | |
| `rich.info.tint` | `rgba(10,132,255,0.2)` | `rgba(10,132,255,0.26)` | |
| `rich.warning.background` | `#FFF8EB` | `#2B1B02` | |
| `rich.warning.border` | `#FFE2B0` | `#4D3205` | |
| `rich.warning.color` | `#9A5B00` | `#FFC56B` | |
| `rich.warning.tint` | `rgba(255,159,10,0.24)` | `rgba(255,159,10,0.28)` | |

## Motion

Durations are in milliseconds. Set any subset with `theme={{ motion: { … } }}`.

| Token | Default | |
|---|---|---|
| `enter` | `350` | Enter animation |
| `exit` | `400` | Exit animation |
| `queueShift` | `230` | The stack moving when a toast joins or leaves |
| `iconPop` | `300` | Icon pop |
| `iconPopDelay` | `120` | Delay before the icon pops |
| `stagger` | `320` | Extra time per position further from the edge |
| `staggerMax` | `900` | Cap on that extra time |
| `enterTranslate` | `0.2` | Enter travel, as a fraction of the toast's height |
| `exitTranslate` | `0.15` | Exit travel |
| `enterScale` | `0.6` | Scale a toast enters from |
| `exitScale` | `0.6` | Scale a toast leaves to |
| `enterEasing` | `Easing.bezier(0.21, 1.02, 0.73, 1)` | Overshoots slightly, as react-hot-toast does |
| `exitEasing` | `Easing.bezier(0.06, 0.71, 0.55, 1)` | Decelerates, without a bounce |
| `iconEasing` | `Easing.bezier(0.175, 0.885, 0.32, 1.275)` | |

Easings are Reanimated easing functions.

---

# Coming from react-hot-toast

> What carries over from the web library, and what is different.

react-hot-toast renders DOM elements, so it runs only on the web; it cannot
render in a native app. This package rebuilds its API on native views, so toast
code written for a React web app ports by changing the import:

```diff
- import toast, { Toaster } from 'react-hot-toast';
+ import toast, { Toaster } from 'expo-hot-toast';
```

## The same

`toast`, `toast.success`, `toast.error`, `toast.loading`, `toast.custom`,
`toast.promise`, `toast.dismiss`, `toast.remove`, `<Toaster>` with
`position`, `toastOptions` (including per-type buckets) and `reverseOrder`,
`<ToastBar>` inside the Toaster's render function, `iconTheme`, `removeDelay`,
`resolveValue` and `useToaster`.

## Different

| react-hot-toast | expo-hot-toast |
|---|---|
| `className` | No CSS here: use `style`, `textStyle` and `theme` |
| `ariaProps` | `accessibilityLabel` and `important` |
| Up to 20 toasts on screen | 3 per position (`visibleToasts`); the rest queue instead of being dropped |
| `gutter` | `gap` (`gutter` still works) |
| `toastLimit` | `visibleToasts` (`toastLimit` still works) |
| `useToaster(toastOptions, toasterId)` | `useToaster({ toastOptions, toasterId })` |
| `calculateOffset`, `updateHeight` | Not needed: layout places toasts |
| `iconTheme.secondary` fills the icon's mark | Accepted, unused: the built-in glyphs are single strokes |

## New

Things react-hot-toast does not have:

- [`action`](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/actions.md) buttons and a [`closeButton`](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/actions.md#a-close-button)
- [Rich toasts](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/rich-toasts.md): progress bars, steps, expandable details, Undo countdowns, notifications, banners, a HUD and the island
- `toast.info`, `toast.warning` and [`toast.update`](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/toast-api.md#toastupdate)
- [Presets, animations, your own icons, a style or class for each part, and theme adapters](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/customizing.md)
- [Swipe to dismiss](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/actions.md#swipe-to-dismiss), and press and hold to pause
- A [`description`](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/toast-types.md#a-description) line, [`richColors`](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/theming.md#rich-colours) and a [collapsed stack](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/positions.md#a-collapsed-stack)
- [`dedupeKey`](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/timing-and-queue.md#deduplication)
- [`onDismiss`](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/toast-types.md#dismiss-and-remove) with a reason
- Duration presets: `'short'`, `'long'`, `'infinite'`
- A [queue](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/timing-and-queue.md#the-visible-limit) with `maxPending` and `dropPolicy`
- Liquid Glass on iOS 26, and [screen reader, Reduce Motion and text size support](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/accessibility.md)

---

# Platform support

> What has been tested where, and known limitations.

## Tested

| Platform | Surface | Status |
|---|---|---|
| iOS 26 | Liquid Glass | The example app runs on an iOS 26.5 simulator in CI, driven by Maestro |
| Android | Material 3 snackbar, opaque | The example app runs on an Android 15 (API 35) emulator in CI, driven by Maestro |
| iOS before 26 | Opaque | Not yet run |
| Web (React DOM, `expo-hot-toast/web`) | Frosted glass | Driven in Chromium through a Vite app, and tested in jsdom in CI; not yet tried inside a Next.js app |
| Web (React Native Web, as in Expo web) | Frosted glass | The example app is built for the web in CI, and every toast on the [home page](https://vanitascaesar1.github.io/expo-hot-toast/) runs on that build |

"Driven by Maestro" means a script taps every row of the example app in light
mode and checks what appears, then repeats a shorter pass in dark mode. The recordings on the
[home page](https://vanitascaesar1.github.io/expo-hot-toast/) come from those runs.

Tested with the versions Expo SDK 57 installs: React Native 0.86,
Reanimated 4.5, Worklets 0.10, Gesture Handler 2.32 and
safe-area-context 5.7.

## Known limitations

- **Native modals cover toasts**, unless you render the Toaster in
  `FullWindowOverlay` on iOS; see [Positions](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/positions.md#above-modals-and-sheets).
- **No morphing between toasts.** iOS 26 can morph one glass shape into
  another, but React Native has no way to drive that with glass yet, so toasts
  enter and leave separately.
- **Android draws an opaque surface.** It does not imitate glass. By default it is a Material 3 snackbar; `preset="glass"` gives the opaque pill instead. You can [pass a blur view](https://vanitascaesar1.github.io/expo-hot-toast/docs/md/customizing.md#blur-on-android) to draw toasts on a blur.
- **The web draws frosted glass, not Liquid Glass.** Browsers have no
  equivalent of Apple's material, so the web gets a CSS backdrop blur. Browsers
  without `backdrop-filter` get the opaque surface.
- **`toast.custom` toasts do not collapse** in a `stacked` Toaster.