Toast

Provider-scoped runtime for toast notifications, exposed via useToast (show/dismiss/dismissAll) with FIFO queueing and safe-area-aware stacking.

Distribution status

BeeUI 0.86.2-rc.3 is public on npm under the opt-in next dist-tag (observed 2026-09-25T06:25:18.371Z). latest currently resolves to 0.86.2-rc.3 and lags next until the owner moves it for all four packages. See Start for the full install commands. The import shape below works against the published package; the repository-local Registry command remains available as a no-registry-required alternative from a BeeUI checkout. Pin @0.86.2-rc.3 instead of @next for an immutable version in CI.

Identity

• Category: Overlays & feedback
• Status: stable public Registry/export-map component family
• Targets: iOS · Android · Web, subject to the compatibility contract
• Prerequisites: @beemvp/beeui-ui installed (or this component’s source copied via the Registry CLI below) and, on Web, the BeeUI Tailwind/Uniwind theme CSS loaded — see Start for full platform setup.
• Source: packages/ui/src/components/toast.tsx

Import

import { TOAST_DEFAULT_DURATION, TOAST_MAX_VISIBLE, useToast } from '@beemvp/beeui-ui';

There is no documented deep/private source import. For source ownership from a BeeUI checkout:

pnpm beeui add toast

Registry (used throughout this page) is BeeUI’s source-ownership manifest — registry/registry.json — that the pnpm beeui/@beemvp/beeui-cli CLI reads to copy a component’s real source into your app and rewrite its internal imports; it is not an npm package index. This component’s own Registry entry: registry/registry.json.

Composition and public API

• Family exports: TOAST_DEFAULT_DURATION TOAST_MAX_VISIBLE useToast
  • Also routed here, outside the Registry family:
    • ToastPlacement
    • ToastRuntimeProviderProps
    • ToastRuntimeProvider
    • toast
  • Package export subpath: @beemvp/beeui-ui/toast

Exported types: ToastAction, ToastApi, ToastDuration, ToastId, ToastOptions, ToastVariant

The generated API inventory is mechanically joined to packages/ui/src/index.ts, Registry metadata, and the component reference contract. Each type’s field table below is parsed directly from that source, not a second hand-maintained copy; for the fuller behavior narrative see the canonical component behavior catalog.

State and behavior contract

Provider-scoped imperative API (useToast().show/dismiss/dismissAll) rather than a controlled component; toasts queue FIFO with at most three visible at once, an explicit persistent mode opts a toast out of auto-dismiss, and action-triggered dismissal is deterministic (never racing the auto-dismiss timer). Stacking position defaults to bottom on iOS/Android and top on Web; override it app-wide with BeeUIProvider’s toastPlacement prop (see the SafeArea page).

Props

ToastAction

Prop	Type	Default	Description
label (required)	string	—	Text of the action button rendered inside the toast.
onPress (required)	() => void	—	Called when the action button is pressed.
dismissOnPress	boolean	—	Dismisses after the callback by default. Set false for an explicit persistent action.

ToastOptions

Prop	Type	Default	Description
title (required)	string	—	Primary line of the toast.
description	string	—	Secondary line under the title.
variant	ToastVariant	—	Semantic surface the toast renders in; each value maps to one surface class.
duration	ToastDuration	—	Auto-dismiss delay in milliseconds, or 'persistent' to stay until dismissed. A value that is not a positive finite number falls back to TOAST_DEFAULT_DURATION (5000).
action	ToastAction	—	An optional action button; see ToastAction.

Related exported types:

• ToastApi — returned by useToast(); not accepted by any prop of this family.

  Member	Type	Description
  show	(options: ToastOptions) => ToastId	Enqueues a toast and returns the id dismiss accepts for it.
  dismiss	(id: ToastId) => void	Dismisses the toast with this id; unknown ids are ignored.
  dismissAll	() => void	Dismisses every shown toast and drops the ones still queued.

• ToastDuration — alias of number | 'persistent'.

• ToastId — alias of string.

• ToastVariant — one of 'neutral', 'success', 'warning', 'destructive', 'info'.

The executable fixtures below are the source-grounded usage examples; consumers should not infer state ownership from DOM structure or another UI library.

Provider and dependencies

• BeeUIProvider is required above this family because it participates in shared overlay/toast runtime infrastructure.
• Peer/native dependencies visible to this Registry item: react, react-native, react-native-safe-area-context
• Registry dependency closure: text, theme, toast-runtime-bridge
• Safe-area ownership remains explicit: shell surfaces touching system edges opt into SafeArea; components do not silently invent app-shell insets.
• Web consumers load the BeeUI semantic theme CSS as documented in Web onboarding.

Platform behavior

This family ships no platform-specific file, but its source branches on Platform, so some behavior differs by target.

The same public family is exposed across the supported target matrix; meaningful platform differences remain governed by the compatibility contract.

Evidence classes are not equal and this page does not blur them: Web behavior is exercised in a real browser, while iOS and Android carry package/export and native-compile evidence, which is not device-runtime proof. The compatibility contract records which class each claim rests on.

Accessibility

• Roles this family assigns: button — set in toast.tsx by the components themselves, not by the caller.
• Accessibility states and properties it sets: accessibilityLabel, accessibilityLiveRegion, accessible — read from toast.tsx.

Keyboard/focus behavior, announcements, Dynamic Type/Web zoom, RTL and reduced-motion expectations are not derived here — see Accessibility overview, Keyboard & focus, RTL/localization and Large text & zoom. BeeUI does not claim universal accessibility certification from automated tests.

Styling and theming

• Style axes: variant (5 values).
• Class-name surfaces: none; this family accepts no className of its own.

Colors, spacing and typography come from semantic tokens rather than from values written here — see Theming and Density. A className is an escape hatch for source-owned and application work, not a cross-engine portability guarantee.

Executable examples

• Primary executable fixture: apps/showcase/__tests__/perf-render-commit.test.tsx
• Additional fixture: apps/showcase/__tests__/semantic-layer-tokens.test.tsx
• Additional fixture: apps/showcase/__tests__/toast.test.tsx
• Additional fixture: apps/showcase/component-gallery/component-gallery.tsx

Addressable examples

Each link below opens the Showcase at that exact example, not at the top of the gallery:

• basic — smallest meaningful complete usage
• states — the states example
• accessibility — the accessibility example
• composition — the composition example

The Showcase links demonstrate Web behavior; use the native-preview guide for real simulator/emulator/device paths.

Live Web preview

This frame loads the real BeeUI Web Showcase on demand; it is not a second docs-only implementation. It proves browser behavior only. Use native preview for iOS/Android simulator, emulator or device paths.

Composition anatomy

• Family root / primary export: TOAST_DEFAULT_DURATION
  • Public composition parts / helpers:
    • TOAST_MAX_VISIBLE
    • useToast
  • Exported type surface:
    • ToastAction
    • ToastApi
    • ToastDuration
    • ToastId
    • ToastOptions
    • ToastVariant

The tree above is ordinary document structure so it remains readable with keyboard and assistive technology; it is derived from the real public export family rather than a canvas-only diagram.

Verified example source

These are the parts of the typechecked runtime Showcase fixture behind this live preview — apps/showcase/component-gallery/component-gallery.tsx, 1103 lines — where Toast is actually used: 54 lines in 3 places. Each block is copied verbatim from the line range named above it, so it is the same executable source, not a retelling of it. The rest of that file exercises other families and is not reproduced here.

Imports the examples below need (a filtered subset of the fixture’s own top-level imports):

import { Button, useToast } from '@beemvp/beeui-ui';
import * as React from 'react';

line 376:

  const toast = useToast();

Fixture state this block reads (same file, lines 376, 377):

  const toast = useToast();
  const [lastAction, setLastAction] = React.useState('No Toast action yet');

lines 386–432:

          <Button
            onPress={() => toast.show({ title: 'Saved', description: 'Default toast with a 5 second timeout.' })}
            size="sm"
            variant="outline"
          >
            Default
          </Button>
          <Button
            onPress={() => toast.show({ title: 'Published', description: 'Changes are live.', variant: 'success' })}
            size="sm"
            variant="outline"
          >
            Success
          </Button>
          <Button
            onPress={() => toast.show({ title: 'Check settings', description: 'One option needs attention.', variant: 'warning' })}
            size="sm"
            variant="outline"
          >
            Warning
          </Button>
          <Button
            onPress={() => toast.show({ title: 'Save failed', description: 'Try the operation again.', variant: 'destructive' })}
            size="sm"
            variant="outline"
          >
            Error
          </Button>
          <Button
            onPress={() => toast.show({
              title: 'Item archived',
              description: 'You can undo this action.',
              variant: 'info',
              action: { label: 'Undo', onPress: () => setLastAction('Undo pressed') },
            })}
            size="sm"
            variant="outline"
          >
            Action
          </Button>
          <Button
            onPress={() => toast.show({ title: 'Persistent notice', description: 'Dismiss this explicitly.', duration: 'persistent', variant: 'info' })}
            size="sm"
            variant="outline"
          >
            Persistent
          </Button>

Fixture state this block reads (same file, line 376):

  const toast = useToast();

lines 436–441:

                toast.show({
                  title: `Queued toast ${index}`,
                  description: index <= 3 ? 'Initially visible.' : 'Promotes FIFO after a visible toast closes.',
                  duration: 'persistent',
                  variant: index % 2 === 0 ? 'info' : 'neutral',
                });

Open the fixture itself for the full surrounding component. For a smaller app-specific example, start from the imports and fixture-state blocks above and keep only the state your screen owns.

Limitations

No Modal/anchored geometry and no arbitrary ReactNode transport; descriptors only.

Related

• All components
• Production patterns
• Showcase
• CLI & source ownership
• Source