@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