npm package: @lucaleukert/expo-toast
Description: Native-feeling liquid-glass toast notifications for Expo (iOS 26+)
Author: Luca Leukert
Latest version: 0.1.1

# expo-toast

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

```bash
bun add expo-toast
```

## 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:

```bash
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

```ts
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

```bash
bun install
bun run build
```

## Run example app (uses local module)

```bash
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:

```bash
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 native projects
- `bun run example:ios` runs the example on a connected iPhone (`--device`)
- `bun run example:device` alias for the same device command