Skip to content
expo-toast

README

Native-feeling liquid-glass toast notifications for Expo with an iOS-native presenter.

V1 scope

  • iOS 15.1+ runtime support
  • Imperative API (toast.show, toast.success, …)
  • Preset variants: success | error | info | loading
  • Up to three visible toasts per edge + FIFO queue
  • Global defaults (toast.configure)
  • Promise helper (toast.promise)
  • Dedupe window + queue drop policy controls
  • Accessibility controls (accessibilityLabel, announce, importance)
  • Reduced-motion aware animations (motion: 'system' | 'full' | 'minimal')
  • Default position: top
  • Default size: fit-content (size: 'fill-width' also supported)
  • Default duration: 3000ms
  • Swipe-up dismiss + one optional action
  • Unsupported platforms: no-op + one dev warning

Install

Install the package in your Expo app:

Terminal window
npx expo install @lucaleukert/expo-toast

If you use Bun directly:

Terminal window
bun add @lucaleukert/expo-toast

expo-toast currently ships an iOS-native presenter. Android and web are safe no-op runtimes.

After installing, regenerate iOS native files and rebuild your dev client/app:

Terminal window
npx expo prebuild --platform ios
npx expo run:ios --device

Documentation

  • Docs site: https://lucaleukert.github.io/expo-toast/
  • Source docs live in docs/ (Astro + Starlight)
  • Root README.md, CHANGELOG.md, and public API JSDoc are synced into docs via:
Terminal window
bun run docs:sync

Publishing (CI/CD)

This repository publishes to npm via GitHub Actions using npm Trusted Publishing (OIDC), not an npm token.

One-time setup:

  1. In npm package settings, add a Trusted Publisher for this GitHub repository and the workflow file: .github/workflows/publish.yml.
  2. Ensure the release is cut from the same repository configured in npm.

Then publish by creating a GitHub Release (published) or running the Publish npm Package workflow manually.

API

import { toast } from 'expo-toast';


toast.success('Saved');


const id = toast.loading('Syncing...');
toast.dismiss(id);

Methods

  • toast.show(options): ToastId
  • toast.success(message, options?)
  • toast.error(message, options?)
  • toast.info(message, options?)
  • toast.loading(message, options?)
  • toast.transition(id, options)
  • toast.update(id, options) (alias for transition)
  • toast.promise(promise, messages, options?)
  • toast.configure(config)
  • toast.dismiss(id?)
  • toast.dismissAll()
  • toast.isSupported(): boolean

Queue controls

Use toast.configure to control queue behavior:

  • maxVisible: max simultaneously visible toasts per edge
  • maxQueue: max pending toasts per edge
  • dropPolicy: 'oldest' | 'newest' when pending queue is full

Compatibility

  • Expo SDK: tested on 54.x
  • React Native: tested on 0.81.x
  • iOS runtime: supported on 15.1+ (native presenter; liquid-glass styling on iOS 26+)
  • Android/Web: API is safe no-op, toast.isSupported() returns false

Build module

Terminal window
bun install
bun run build

Run example app (uses local module)

Terminal window
cd example
bun install
bun run prebuild
bun run ios

bun run ios uses expo run:ios --device and targets your connected iPhone.

For JS-only iteration:

Terminal window
bun run start

Repository scripts

  • bun run build builds module typings + JS output
  • bun run docs:sync syncs README/CHANGELOG + generated JSDoc API docs into docs reference pages
  • bun run docs:check-sync verifies docs references are in sync
  • bun run docs:dev runs the Astro docs site locally
  • bun run docs:build builds the Astro docs site
  • bun run lint runs Biome lint checks
  • bun run format formats code with Biome
  • bun run format:check checks formatting with Biome
  • bun run lint:expo runs Expo module lint checks
  • bun run example:start starts the example app
  • bun run example:prebuild prebuilds the example iOS native project
  • bun run example:ios runs the example on a connected iPhone (--device)
  • bun run example:device alias for the same device command