@capgo/capacitor-pretty-toast

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

Demo

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.

| 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