@capgo/capacitor-pretty-toast

Show beautiful toast notifications in your Capacitor app with native overlays on iOS and Android and a DOM renderer on web. Same toast.* API as react-native-pretty-toast.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-pretty-toast in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-pretty-toast to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Variants: success(), error(), info(), warning(), loading() and fully custom show().
• Promise toasts: promise() shows loading, then success or error when your promise settles.
• Live updates: update() changes a toast in place, dismiss() and dismissAll() close them.
• Queueing: toasts queue by default, and force puts the new toast first and shows it once the current toast is dismissed.
• Icons: symbol icons and raw SVG through icon, and image URIs through iconSource.
• Platforms: iOS, Android and Web.

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);

API

• show(...)
• success(...)
• error(...)
• info(...)
• warning(...)
• loading(...)
• update(...)
• promise(...)
• dismiss(...)
• dismissAll()
• Interfaces
• Type Aliases

Public toast controller exposed as toast.

show(...)

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

Show a custom toast and return its id.

Returns: string

success(...)

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

Show a success toast.

Returns: string

error(...)

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

Show an error toast.

Returns: string

info(...)

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

Show an informational toast.

Returns: string

warning(...)

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

Show a warning toast.

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.

Returns: string

update(...)

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

Update an existing toast by id.

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.

Returns: Promise<T>

dismiss(...)

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

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

dismissAll()

dismissAll() => void

Dismiss the current toast and clear the queue.

Interfaces

ToastConfig

ToastAction

ShowOptions

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