react-native-toastcraft

React Native toast notifications for Expo and bare React Native apps. react-native-toastcraft gives you swipe-to-dismiss toasts, promise toasts, loading states, action buttons, progress bars, queue management, Reanimated transitions, optional haptic feedback, and an imperative API that feels as simple as console.log.

Why react-native-toastcraft

Most React Native toast libraries force a tradeoff between ease of use and modern UX. react-native-toastcraft is designed to cover both.

• Fast setup for Expo and bare React Native projects
• Reanimated-powered motion on the UI thread
• Gesture Handler swipe dismissal with pause and spring-back behavior
• Familiar imperative API: toast(), toast.success(), toast.error(), toast.loading(), toast.promise(), toast.update(), and toast.action()
• Queue, stack, and replace modes for real product flows
• Built-in progress bars, loading spinner variants, action buttons, theme primitives, and optional haptic feedback
• Accessibility-aware defaults including screen reader announcements, reduced motion support, and longer readable durations for screen-reader users

Features

• Toast provider and portal rendering
• Success, error, warning, info, loading, custom, and action toasts
• Promise-based loading to success or error transitions
• Update and dismiss APIs
• Queue, stack, and replace behaviors
• Reanimated entry and exit presets with smart direction defaults
• Swipe-to-dismiss using React Native Gesture Handler
• Loading spinner variants: spinner, dots, and pulse
• Built-in progress bar support for timed toasts
• Optional Expo haptic feedback integration when expo-haptics is installed
• Screen-reader-aware duration extension for timed toasts
• Light and dark theme primitives plus createTheme()
• TypeScript types, linting, unit tests, and copy-pasteable usage examples

Installation

Install the package and required peer dependencies:

npm install react-native-toastcraft react-native-reanimated react-native-gesture-handler

Optional haptics support:

npm install expo-haptics

If you use Expo, install the peer dependencies with Expo-compatible versions.

Required setup

react-native-toastcraft depends on the standard Reanimated and Gesture Handler app setup.

1. Import Gesture Handler at the top of your entry file when your app setup requires it.
2. Wrap your app in GestureHandlerRootView.
3. Ensure the Reanimated Babel plugin is enabled in your Babel config.

Typical Babel setup:

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: ['react-native-reanimated/plugin'],
};

Quick start

Wrap your app once:

import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { ToastProvider } from 'react-native-toastcraft';

export function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <ToastProvider>
        <RootNavigator />
      </ToastProvider>
    </GestureHandlerRootView>
  );
}

Then trigger toasts from anywhere:

import { toast } from 'react-native-toastcraft';

toast('Hello world');
toast.success('Profile saved');
toast.error('Could not save changes');

const loadingId = toast.loading('Uploading photo...', {
  spinnerVariant: 'dots',
  hapticFeedback: false,
});

toast.action('File deleted', {
  label: 'Undo',
  onPress: () => restoreFile(),
});

setTimeout(() => {
  toast.update(loadingId, {
    type: 'success',
    message: 'Upload complete',
  });
}, 1500);

API overview

Basic toasts

toast('Heads up');
toast.success('Saved');
toast.error('Something went wrong');
toast.warning('Check your connection');
toast.info('A new version is ready');

Loading and promise toasts

toast.loading('Syncing data', {
  spinnerVariant: 'pulse',
});

await toast.promise(syncAccount(), {
  loading: 'Syncing...',
  success: 'Everything is up to date',
  error: 'Sync failed',
});

Action toasts

toast.action('File moved to trash', {
  label: 'Undo',
  onPress: () => restoreFile(),
});

Update and dismiss

const id = toast.loading('Publishing...');

toast.update(id, {
  type: 'success',
  message: 'Post published',
  config: {
    duration: 3000,
    progressBarColor: '#10B981',
  },
});

toast.dismiss(id);
toast.dismiss();

Custom rendering

toast.custom(({ dismiss, progress }) => (
  <CustomToastCard progress={progress} onClose={dismiss} />
));

Provider configuration

Configure the provider globally and override any option per toast.

<ToastProvider
  config={{
    position: 'top-center',
    offset: 56,
    maxVisible: 3,
    stackBehavior: 'stack',
    animationDuration: 240,
    swipeToDismiss: true,
    swipeDirection: 'up',
    swipeThreshold: 56,
    showProgressBar: true,
    spinnerVariant: 'spinner',
    hapticFeedback: true,
    hapticStyle: 'light',
    extendDurationForScreenReader: true,
  }}
>
  <App />
</ToastProvider>

Useful config fields:

• position: top, bottom, or center placement options
• stackBehavior: stack, replace, or queue
• duration: auto-dismiss timing in milliseconds
• persistent: disables auto-dismiss for manual flows
• action: attaches an inline action button and uses a longer default duration
• showProgressBar: shows the countdown bar for timed toasts
• progressBarColor: overrides the progress color for a specific toast
• spinnerVariant: spinner, dots, or pulse
• hapticFeedback and hapticStyle: optional Expo haptic feedback control
• extendDurationForScreenReader: makes timed toasts easier to consume with assistive tech
• enterAnimation and exitAnimation: override the smart defaults
• swipeToDismiss, swipeDirection, swipeThreshold: gesture behavior controls

Included examples

The package includes focused example snippets in examples/README.md:

• examples/basic-usage.tsx: minimal provider setup and preset toasts
• examples/provider-config.tsx: global queue, gesture, haptic, and accessibility config
• examples/promise-and-action.tsx: promise toasts and action toasts
• examples/custom-render.tsx: custom rendering with the progress render prop

Accessibility

The current implementation includes:

• Screen reader announcements for string-based toast messages
• Alert semantics for error and warning toasts
• Reduced motion support through Reanimated's useReducedMotion()
• Pause-on-press behavior so timed toasts are easier to read and interact with
• Screen-reader-aware duration extension for auto-dismissing toasts

Feature snapshot

| Feature | Current support | | --- | --- | | Imperative API | Yes | | Success, error, warning, info toasts | Yes | | Loading toasts | Yes | | Promise toasts | Yes | | Action toasts | Yes | | Custom render toasts | Yes | | Progress bar | Yes | | Queue, stack, replace | Yes | | Swipe to dismiss | Yes | | Reduced motion | Yes | | Theme factory | Yes | | Optional Expo haptics | Yes | | Included usage examples | Yes | | Example app and docs site | Not yet |

Why developers search for this package

If you are looking for any of the following, react-native-toastcraft is built to fit:

• React Native toast notifications
• Expo toast library
• React Native snackbar alternative
• Reanimated toast notifications for React Native
• Swipe dismiss toast for React Native
• Promise toasts in React Native
• TypeScript toast library for Expo apps
• React Native toast library with haptic feedback
• Accessible toast notifications for React Native

Publishing checklist

Before publishing a release:

1. Run npm run build
2. Run npm run type-check
3. Run npm run lint
4. Run npm test
5. Run npm pack
6. Verify the npm package name is still available
7. Publish with npm publish

Development

npm install
npm run type-check
npm run lint
npm test
npm run build

License

MIT