Toast

Stackable toast notification system with rich colors, swipe-to-dismiss, and a Sonner-like imperative API.

iOSAndroid

Preview Toast on your device

Scan with Expo Go

Download Expo Go, then scan the QR code to preview native components.

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-toast

Required Packages(3 packages)

pnpm add react-native-gesture-handler react-native-reanimated react-native-worklets

Usage

Wrap your app with <Toaster> and use the imperative toast API or the useToaster hook.

import { Toaster, toast } from '@/components/docyrus-native/toast';

// Wrap your app
function App() {
  return (
    <Toaster position="top-center" richColors>
      <MyScreen />
    </Toaster>
  );
}

// Fire toasts from anywhere
toast.success('Changes saved');
toast.error('Upload failed');
toast.warning('Disk almost full');
toast.info('New update available');
toast.loading('Processing...');

Toaster Props

Prop	Type	Default	Description
`children`	`ReactNode`	—	App content to wrap
`position`	`ToastPosition`	`'bottom-center'`	Default position for toasts
`duration`	`number`	`4000`	Auto-dismiss duration in ms
`gap`	`number`	`1`	Gap between stacked toasts
`visibleToasts`	`number`	`3`	Maximum visible toast count
`swipeDirection`	`'up' \| 'down' \| 'left' \| 'right'`	`'up'`	Swipe direction to dismiss
`richColors`	`boolean`	`true`	Use colored backgrounds per variant
`closeButton`	`boolean`	`false`	Show close button on all toasts
`swipeThreshold`	`number`	`100`	Swipe distance to trigger dismiss
`titleMaxLines`	`number`	`2`	Maximum title text lines
`descMaxLines`	`number`	`3`	Maximum description text lines
`variantColors`	`Partial<Record<ToastType, Partial<ToastVariantColors>>>`	—	Override default variant colors

ToastData Props

Prop	Type	Default	Description
`id`	`string \| number`	—	Unique toast identifier (auto-generated)
`type`	`'success' \| 'error' \| 'info' \| 'warning' \| 'default' \| 'loading'`	`'default'`	Toast variant type
`title`	`ReactNode`	—	Toast title content
`description`	`ReactNode`	—	Toast description content
`duration`	`number`	`4000`	Auto-dismiss duration in ms
`action`	`ToastAction`	—	Action button with label and onClick
`icon`	`ReactNode`	—	Custom icon element
`closeButton`	`boolean`	`false`	Show close button
`important`	`boolean`	—	Prevent auto-dismiss
`onDismiss`	`(toast: ToastData) => void`	—	Called when toast is dismissed
`onAutoClose`	`(toast: ToastData) => void`	—	Called when toast auto-closes
`dismissible`	`boolean`	`true`	Allow swipe-to-dismiss
`position`	`ToastPosition`	—	Override default position for this toast
`className`	`string`	—	Toast container CSS classes
`titleLines`	`number`	—	Override title max lines
`descLines`	`number`	—	Override description max lines
`colors`	`Partial<ToastVariantColors>`	—	Override variant colors for this toast

Type Exports

Type	Description
`ToasterProps`	Props for Toaster provider component
`ToastData`	Individual toast data object
`ToastType`	`'success' \| 'error' \| 'info' \| 'warning' \| 'default' \| 'loading'`
`ToastPosition`	`'top-center' \| 'bottom-center' \| 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'`
`ToastAction`	`{ label: string; onClick: () => void }`
`ToastVariantColors`	`{ bg: string; fg: string; icon?: string; border?: string }`