@capgo/capacitor-pretty-toast

June 16, 2026 · View on GitHub

Native-first pretty toast notifications for Capacitor and the web.

Demo

Animated Pretty Toast demo on an external device

This package keeps the familiar toast.* surface from react-native-pretty-toast, but ships as a Capacitor plugin with:

native overlays on iOS and Android.
a DOM renderer on web.
queueing, force, update, dismiss, dismissAll, and promise
symbol icons, raw SVG through icon, and URI-based images through iconSource

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-pretty-toast` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-pretty-toast

Then sync native platforms:

bunx cap sync

Usage

import { toast } from '@capgo/capacitor-pretty-toast';

toast.success('Saved', {
  message: 'Your changes are already on disk.',
});

const id = toast.loading('Uploading', {
  message: 'This toast stays visible until you update it.',
});

setTimeout(() => {
  toast.update(id, {
    title: 'Upload complete',
    message: 'Updated in place without replaying the enter animation.',
    icon: 'checkmark.circle.fill',
    autoDismiss: true,
  });
}, 1500);

Public toast controller exposed as toast.

show(...)

show(config: ToastConfig, options?: ShowOptions | undefined) => string

Show a custom toast and return its id.

Param	Type
`config`	`ToastConfig`
`options`	`ShowOptions`

Returns: string

success(...)

success(title: string, config?: ToastConfig | undefined, options?: ShowOptions | undefined) => string

Show a success toast.

Param	Type
`title`	`string`
`config`	`ToastConfig`
`options`	`ShowOptions`

Returns: string

error(...)

error(title: string, config?: ToastConfig | undefined, options?: ShowOptions | undefined) => string

Show an error toast.

Param	Type
`title`	`string`
`config`	`ToastConfig`
`options`	`ShowOptions`

Returns: string

info(...)

info(title: string, config?: ToastConfig | undefined, options?: ShowOptions | undefined) => string

Show an informational toast.

Param	Type
`title`	`string`
`config`	`ToastConfig`
`options`	`ShowOptions`

Returns: string

warning(...)

warning(title: string, config?: ToastConfig | undefined, options?: ShowOptions | undefined) => string

Show a warning toast.

Param	Type
`title`	`string`
`config`	`ToastConfig`
`options`	`ShowOptions`

Returns: string

loading(...)

loading(title: string, config?: ToastConfig | undefined, options?: ShowOptions | undefined) => string

Show a loading toast. Loading toasts do not auto-dismiss by default.

Param	Type
`title`	`string`
`config`	`ToastConfig`
`options`	`ShowOptions`

Returns: string

update(...)

update(id: string, partial: ToastConfig) => void

Update an existing toast by id.

Param	Type
`id`	`string`
`partial`	`ToastConfig`

promise(...)

promise<T>(promise: Promise<T>, messages: PromiseMessages<T>) => Promise<T>

Show a loading toast while a promise is pending, then update it for success or error.

Param	Type
`promise`	`Promise<T>`
`messages`	`PromiseMessages<T>`

Returns: Promise<T>

dismiss(...)

dismiss(id?: string | undefined) => void

Dismiss one toast by id, or the current toast when no id is provided.

Param	Type
`id`	`string`

dismissAll()

dismissAll() => void

Dismiss the current toast and clear the queue.

Interfaces

ToastConfig

Prop	Type	Description
`id`	`string`	Optional stable toast id. A generated id is returned when omitted.
`icon`	`string`	Accepts either an SF-symbol-like identifier or raw SVG markup. SVG mode is enabled only when the string starts with `<svg` after trim.
`iconSource`	`IconSource`	URI-like image source. Supports `https://`, `http://`, `file://`, absolute file paths, `data:` URLs, `blob:` URLs, or `{ uri }`. `iconSource` always wins over `icon`.
`title`	`string`	Main toast title.
`message`	`string`	Secondary toast message.
`duration`	`number`	Auto-dismiss delay in milliseconds.
`autoDismiss`	`boolean`	Whether the toast dismisses itself after `duration`.
`enableSwipeDismiss`	`boolean`	Whether swipe-to-dismiss is enabled on native overlays.
`accentColor`	`string`	CSS-style accent color used by native/web renderers.
`strokeColor`	`string`	CSS-style border/stroke color.
`disableBackdropSampling`	`boolean`	Disable Android/iOS backdrop sampling behind the toast.
`action`	`ToastAction`	Optional action button configuration.
`accessibilityAnnouncement`	`string`	Text announced to assistive technologies when the toast is shown.
`onPress`	`(() => void)`	Called when the toast body is pressed.
`onShow`	`(() => void)`	Called when the toast becomes visible.
`onHide`	`(() => void)`	Called when the toast is dismissed.
`onAutoDismiss`	`(() => void)`	Called when the toast is dismissed by its timer.

ToastAction

Prop	Type	Description
`label`	`string`	Text shown for the native/web action button.
`onPress`	`() => void`	Called when the action button is pressed.

ShowOptions

Prop	Type	Description
`force`	`boolean`	Dismiss the current toast and show this one immediately.

Type Aliases

IconSource

string | { uri: string }

PromiseMessages

{ loading: string | ToastConfig; success: string | ((value: T) => string | ToastConfig); error: string | ((error: unknown) => string | ToastConfig); }

Notes:

Raw SVG is accepted only through icon.
iconSource always takes precedence over icon.
toast.loading() defaults autoDismiss to false.

Example App

The repo includes example-app/, a Vite-based Capacitor app with demos for:

every toast.* method
queueing and force
live update
dismiss and dismissAll
promise
symbol icons
raw SVG icons
remote and data-URL iconSource values
repeatable capture modes with ?demo=hero, ?demo=flow, and ?demo=update

?demo=flow is the promo enter/exit morph used in the README video. The shipped video shows both the Android cutout path and the centered island-style path side by side.

Run it locally:

cd example-app
bun install
bun run start

Development

bun install
bun run build
bun test
bun run verify