API Reference

This page is generated by scripts/sync-api-docs.mjs. Do not edit manually.

Functions

normalizeDuration

normalizeDuration(duration: ToastDuration | undefined, variant: ToastVariant): number

Normalizes toast duration presets into milliseconds.

• undefined => 3000ms, except loading toasts which default to infinite.
• short => 2000ms
• long => 4500ms
• infinite => -1 (native no-timeout sentinel)

Numeric values are rounded and clamped to >= 0.

parseIOSMajorVersion

parseIOSMajorVersion(version: string | number): number

Parses an iOS runtime version into its major integer.

Accepts either a numeric version (17) or dotted string (17.4.1). Invalid values resolve to 0.

runtimeSupportsToastFor

runtimeSupportsToastFor(os: string, _version: string | number): boolean

Returns whether the provided runtime tuple is eligible for native toast support checks.

This is exported for testability and future-proof runtime gating logic. The current v1 implementation supports iOS only.

Objects

toast

toast: ToastApi

Imperative toast API for showing, updating, and dismissing toasts.

This is the primary public surface of expo-toast. All methods are no-op safe on unsupported platforms and can be called unconditionally.

Interfaces

ToastAction

interface ToastAction

Action button configuration for a toast.

Exactly one action is supported per toast.

Members

label

label: string;

Action button label shown in the trailing action area.

onPress

onPress?: (event: ToastActionPressEvent) => void;

Handler called when the action button is pressed.

This callback is optional. If omitted, the button still renders but does not invoke custom JS behavior.

ToastApi

interface ToastApi

Public imperative API exposed as toast.

Members

show

show(options: ToastOptions): ToastId;

Shows a toast with full control over content and behavior.

Returns the active toast id. On unsupported runtimes, this is a safe no-op and still returns a deterministic id.

transition

transition(id: ToastId, options: ToastTransitionOptions): ToastId;

Transitions an existing toast by id.

Use to update content, variant, duration, action, or accessibility settings of a toast that is currently visible or queued.

update

update(id: ToastId, options: ToastTransitionOptions): ToastId;

Alias for ToastApi.transition.

success

success(message: string, options?: ToastMessageOptions): ToastId;

Shows a success toast.

error

error(message: string, options?: ToastMessageOptions): ToastId;

Shows an error toast.

info

info(message: string, options?: ToastMessageOptions): ToastId;

Shows an info toast.

loading

loading(message: string, options?: ToastMessageOptions): ToastId;

Shows a loading toast.

promise

promise<T>( work: Promise<T>, messages: ToastPromiseMessages<T>, options?: ToastPromiseOptions, ): Promise<T>;

Binds toast state to a promise lifecycle.

Shows a loading toast immediately, then transitions it to success or error based on the promise result, returning the original promise outcome.

configure

configure(config: ToastConfig): void;

Updates global runtime defaults.

This call is additive: only provided keys are changed.

dismiss

dismiss(id?: ToastId): void;

Dismisses one toast by id, or all toasts when id is omitted.

When no id is passed, behavior matches ToastApi.dismissAll.

dismissAll

dismissAll(): void;

Dismisses all visible and queued toasts.

isSupported

isSupported(): boolean;

Returns whether native runtime support is currently available.

In this version, support is available on iOS native runtimes with the module linked into the app binary. Android and web return false.

ToastConfig

interface ToastConfig

Global runtime defaults and queue controls.

Applied through ToastApi.configure. Calling configure merges values into the current runtime config; omitted fields keep their previous values.

Members

duration

duration?: ToastDuration;

Default duration for new toasts.

position

position?: ToastPosition;

Default render position.

size

size?: ToastSize;

Default width behavior.

haptics

haptics?: boolean;

Default haptics behavior.

announce

announce?: boolean;

Default announcement behavior.

importance

importance?: ToastImportance;

Default accessibility importance.

motion

motion?: ToastMotionPreference;

Default motion behavior.

dedupeWindowMs

dedupeWindowMs?: number;

Time window used to dedupe matching toasts in milliseconds.

0 disables dedupe. Values are rounded and clamped to >= 0.

maxVisible

maxVisible?: number;

Maximum simultaneously visible toasts per edge.

maxQueue

maxQueue?: number;

Maximum queued pending toasts per edge.

0 disables queuing entirely.

dropPolicy

dropPolicy?: ToastDropPolicy;

Queue eviction strategy when maxQueue is exceeded.

ToastOptions

interface ToastOptions

Full options used when showing a toast.

This is the most complete shape accepted by ToastApi.show.

Members

id

id?: ToastId;

Explicit id to use for the toast.

If omitted, an id is generated. Reusing ids intentionally can simplify update flows, but you should avoid accidental collisions.

variant

variant?: ToastVariant;

Visual style preset.

Defaults to 'info'.

title

title?: string;

Optional title text shown above ToastOptions.message.

message

message: string;

Main toast body text.

action

action?: ToastAction;

Optional action button.

duration

duration?: ToastDuration;

Display duration in milliseconds or semantic preset.

If omitted, the global config duration is used. If both are omitted: loading defaults to infinite and other variants default to 3000ms.

position

position?: ToastPosition;

Screen edge used for rendering.

Falls back to the current global config position.

size

size?: ToastSize;

Width behavior for this toast.

Falls back to the current global config size.

haptics

haptics?: boolean;

Enables haptic feedback when showing the toast.

dedupeKey

dedupeKey?: string;

Key used for dedupe matching within the active dedupeWindowMs.

If omitted, the message text is used as the dedupe key.

accessibilityLabel

accessibilityLabel?: string;

Accessibility label override announced by assistive technologies.

announce

announce?: boolean;

Whether this toast should trigger an accessibility announcement.

If omitted, defaults are derived from importance and global config.

importance

importance?: ToastImportance;

Accessibility importance for announcement behavior and native hinting.

motion

motion?: ToastMotionPreference;

Motion behavior override for this toast.

onShow

onShow?: (event: ToastShowEvent) => void;

Called when the toast is shown.

This callback is associated with this toast id only.

onDismiss

onDismiss?: (event: ToastDismissEvent) => void;

Called when the toast is dismissed.

Fires for timeout, gesture, programmatic dismissal, and replacement cases.

ToastPromiseMessages

interface ToastPromiseMessages

Text messages used by ToastApi.promise.

Members

loading

loading: string;

Message shown while the promise is pending.

success

success: string | ((value: T) => string);

Success message or mapper using the resolved value.

The function form lets you generate context-aware success text.

error

error: string | ((error: unknown) => string);

Error message or mapper using the rejection reason.

The function form receives the original rejection value.

ToastPromiseOptions

interface ToastPromiseOptions

Optional per-state options for ToastApi.promise.

These options are merged into each corresponding lifecycle toast.

Members

loading

loading?: ToastMessageOptions;

Extra options for the loading toast.

success

success?: ToastMessageOptions;

Extra options for the success transition.

error

error?: ToastMessageOptions;

Extra options for the error transition.

ToastTransitionOptions

interface ToastTransitionOptions

Options used to update an existing toast.

All fields are optional and only provided keys are changed.

Members

variant

variant?: ToastVariant;

New variant to apply.

title

title?: string;

New title text.

message

message?: string;

New body text.

action

action?: ToastAction | null;

Action button update.

• undefined: keep current action.
• null: clear current action.
• ToastAction: replace current action.

duration

duration?: ToastDuration;

New duration in milliseconds or semantic preset.

size

size?: ToastSize;

New width behavior.

haptics

haptics?: boolean;

Haptics override for this transition.

accessibilityLabel

accessibilityLabel?: string;

Accessibility label override.

announce

announce?: boolean;

Announcement behavior override.

importance

importance?: ToastImportance;

Accessibility importance override.

motion

motion?: ToastMotionPreference;

Motion behavior override.

onDismiss

onDismiss?: (event: ToastDismissEvent) => void;

Dismiss callback replacement for this toast id.

If omitted, the previous callback is retained.

Type Aliases

ExpoToastModuleEvents

type ExpoToastModuleEvents = { onToastShow: (event: ToastShowEvent) => void; onToastDismiss: (event: ToastDismissEvent) => void; onToastActionPress: (event: ToastActionPressEvent) => void; }

Native module event callbacks exposed by expo-toast.

These are internal event channels consumed by the JS runtime wrapper and are not subscribed directly in normal app usage.

ToastActionPressEvent

type ToastActionPressEvent = { id: ToastId; variant: ToastVariant; title: string | null; message: string; position: ToastPosition; }

Event emitted when a toast action button is pressed.

Includes the id and resolved metadata of the toast at the moment the action was invoked.

ToastDismissEvent

type ToastDismissEvent = { id: ToastId; reason: ToastDismissReason; }

Event emitted when a toast is dismissed.

Dismiss callbacks receive this payload to identify which toast ended and why.

ToastDismissReason

type ToastDismissReason = 'timeout' | 'swipe' | 'programmatic' | 'replaced'

Reason the toast left the screen.

• timeout: auto-dismiss after duration elapsed.
• swipe: user dismissed with a gesture.
• programmatic: dismissed via API (dismiss / dismissAll).
• replaced: toast was replaced by transition or queue behavior.

ToastDropPolicy

type ToastDropPolicy = 'oldest' | 'newest'

Queue eviction strategy when pending queue capacity is reached.

• oldest: remove the oldest pending toast and enqueue the new one.
• newest: discard the newly requested toast when the queue is full.

ToastDuration

type ToastDuration = number | 'short' | 'long' | 'infinite'

Display duration in milliseconds or a semantic preset.

Presets are converted by normalizeDuration:

• short => 2000ms
• long => 4500ms
• infinite => never auto-dismisses

Numeric values are rounded to integers and clamped to >= 0.

ToastId

type ToastId = string

Unique identifier for a toast instance.

This id is returned by all show-style APIs and can be used later with ToastApi.transition, ToastApi.update, or ToastApi.dismiss. If you do not provide one explicitly in ToastOptions.id, the library generates a unique value.

ToastImportance

type ToastImportance = 'low' | 'normal' | 'high'

Accessibility/announcement priority for a toast.

Importance controls announcement behavior defaults and ordering hints passed to native accessibility APIs.

ToastMessageOptions

type ToastMessageOptions = Omit<ToastOptions, 'message' | 'variant'>

Shared toast options for convenience APIs that provide message/variant separately.

Used by toast.success, toast.error, toast.info, and toast.loading.

ToastMotionPreference

type ToastMotionPreference = 'system' | 'full' | 'minimal'

Motion behavior preference.

• system: follows the OS “Reduce Motion” setting.
• full: always uses full animation.
• minimal: uses reduced-motion transitions regardless of OS setting.

ToastPosition

type ToastPosition = 'top' | 'bottom'

Screen edge where a toast stack is rendered.

Toast queues are maintained per edge, so top and bottom are independent visible/pending stacks.

ToastShowEvent

type ToastShowEvent = { id: ToastId; }

Event emitted when a toast is presented.

Triggered once the native presenter has accepted and displayed the toast.

ToastSize

type ToastSize = 'fit-content' | 'fill-width'

Width behavior for a toast.

• fit-content: width grows to content with system-defined bounds.
• fill-width: toast stretches to the available horizontal safe area.

ToastVariant

type ToastVariant = 'success' | 'error' | 'info' | 'loading'

Visual style preset for a toast.

• success: positive confirmation.
• error: failure state.
• info: neutral status update.
• loading: in-progress state, defaults to an infinite duration until updated/dismissed.