goey-native-toast

Features

• 🚀 60fps Animations: Powered by Reanimated v3/v4 for buttery smooth enter/exit transitions.
• 🧬 Smart Morphing: Starts as a compact pill and seamlessly morphs to show more content (description/actions) if needed.
• 👆 Interactive: Swipe to dismiss support with configurable directions.
• 🎨 Themable: Built-in support for light, dark, and system themes, plus a "solid" color mode.
• 📍 Flexible Positioning: Support for 6 positions: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right. Multiple positions can be used simultaneously!
• ⌨️ Keyboard Aware: Automatically adjusts position when the keyboard opens/closes (powered by react-native-keyboard-controller).
• 🧩 Headless Capable: Fully customizable body content.
• 📱 Cross Platform: Works seamlessly on iOS and Android.
• ⚡ Zero Config: Works out of the box with sensible defaults.
• 🔄 Promise Support: Built-in loading/success/error states for async operations.
• ⏱️ Auto-Dismiss Control: Configurable duration with manual dismiss option.

Installation

npm install goey-native-toast
# or
yarn add goey-native-toast
# or
pnpm add goey-native-toast

Peer Dependencies

This library relies on several peer dependencies that must be installed in your project:

npx expo install react-native-reanimated react-native-gesture-handler react-native-svg react-native-safe-area-context react-native-worklets

Note: react-native-worklets is required when using react-native-reanimated v4+. It provides the worklet runtime for Reanimated's UI thread animations.

Optional:

npx expo install react-native-keyboard-controller

(Recommended for keyboard avoidance support. If not installed, toasts will simply ignore keyboard state.)

Expo Support

✅ Expo Snack & Expo Go: Supported! (Keyboard avoidance will be disabled) ✅ Expo Development Builds: Fully supported with keyboard avoidance.

To enable full keyboard support in Development Builds:

1. Install the package: npx expo install react-native-keyboard-controller
2. Add plugin to app.json:

   {
     "expo": {
       "plugins": [
         "react-native-keyboard-controller"
       ]
     }
   }

3. Rebuild: npx expo prebuild then run your app.

Bare React Native

Ensure you have configured react-native-reanimated and react-native-gesture-handler according to their respective documentation (e.g., wrapping your app in GestureHandlerRootView, adding the Babel plugin).

Usage

1. Add the Toaster

Place the <Toaster /> component at the root of your application (or near the top level). It renders the toast stack.

import { Toaster } from 'goey-native-toast';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      {/* Your app content */}
      <Toaster />
    </GestureHandlerRootView>
  );
}

2. Trigger Toasts

Import the toast object to trigger notifications from anywhere in your app.

import { toast } from 'goey-native-toast';
import { Button } from 'react-native';

// ... inside your component
<Button title="Success" onPress={() => toast.success('Event created successfully')} />
<Button title="Error" onPress={() => toast.error('Something went wrong')} />

Toast Types

Standard Toasts

toast.success('Successfully saved!');
toast.error('Error saving data');
toast.warning('Please review your input');
toast.info('New version available');

Loading Toast

Shows a loading toast with an infinite duration. Useful for long-running operations.

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

// Later, update the toast
toast.update(id, {
  type: 'success',
  title: 'Complete!',
  description: 'Your file has been uploaded.',
  duration: 3000,
});

With Description

Add a detailed description to any toast. The toast will automatically "morph" and expand to fit the content.

toast.success('File Uploaded', {
  description: 'image_v1.png has been added to your gallery.',
  expandWithSpring: true, // Use spring animation (default) or false for timing
});

With Action

Add an action button to the toast.

toast.error('Connection Lost', {
  action: {
    label: 'Retry',
    onClick: () => reloadData(),
  },
});

With Cancel Button

Add a cancel button alongside the action button.

toast.warning('Unsaved Changes', {
  action: {
    label: 'Save',
    onClick: () => saveData(),
  },
  cancel: {
    label: 'Discard',
    onClick: () => discardChanges(),
  },
});

Custom Body Content

You can render custom React nodes inside the toast body. The toast header (icon + title) will remain, and the body will expand to show your custom content.

toast.custom('Now Playing', {
  customBody: (
    <View style={{ padding: 8 }}>
      <Text>Neon Nights - Synthwave Collective</Text>
      <View style={{ flexDirection: 'row', marginTop: 8 }}>
        <Button title="⏸️" onPress={() => {}} />
        <Button title="⏭️" onPress={() => {}} />
      </View>
    </View>
  ),
});

Promise Toast

Handle async operations with automatic loading, success, and error states.

const myPromise = new Promise((resolve) =>
  setTimeout(() => resolve({ name: 'User Data' }), 2000)
);

toast.promise(myPromise, {
  loading: 'Loading data...',
  success: (data) => `Successfully loaded ${data.name}`,
  error: (err) => `Error: ${err.message}`,
}, {
  expandWithSpring: true, // Optional: apply to all states
});

Dismissing Toasts

// Dismiss a specific toast by ID
const id = toast.info('This will be dismissed soon');
toast.dismiss(id);

// Dismiss all toasts at once
toast.dismiss();

Manual Dismiss Only

Create a toast that won't auto-dismiss until manually dismissed.

toast.custom('Action Required', {
  autoDismiss: false,
  duration: Infinity,
  action: {
    label: 'Dismiss',
    onClick: () => toast.dismiss(id),
  },
});

Simultaneous Positions

Trigger toasts in different positions at the same time.

toast.success('Top Left!', { position: 'top-left' });
toast.info('Top Right!', { position: 'top-right' });
toast.warning('Bottom Left!', { position: 'bottom-left' });
toast.error('Bottom Right!', { position: 'bottom-right' });

API Reference

<Toaster /> Props

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | position | ToastPosition | 'top-center' | Default position for toasts. Options: 'top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'. | | visibleToasts | number | 3 | Maximum number of toasts visible at once. | | duration | number | 4000 | Default duration in milliseconds before auto-dismissing. | | theme | 'light' \| 'dark' \| 'system' | 'system' | Color theme of the toasts. | | solidColors | boolean | false | Use solid background colors (e.g., green for success) instead of standard black/white. | | offset | number | 16 | Distance from the safe area edge. | | gutter | number | 8 | Spacing between stacked toasts. | | swipeToDismissDirection | SwipeDirection | undefined | Direction to swipe to dismiss. Defaults to natural direction based on position. | | icons | Partial<Record<ToastType, ReactNode>> | {} | Custom icons for each toast type. | | toastOptions | Partial<ToastConfig> | {} | Global default options for all toasts. | | closeButton | boolean | false | Show a close button on all toasts. | | dir | 'ltr' \| 'rtl' \| 'auto' | 'auto' | Text direction. | | reverseOrder | boolean | false | Reverse the order of toasts (newest on top). | | containerStyle | ViewStyle | undefined | Custom style for the toast container. | | toastClassName | string | undefined | Custom class name for all toasts (NativeWind/Tailwind). | | expand | boolean | false | Whether toasts are expanded by default. | | hotkey | string[] | undefined | Keyboard shortcuts to dismiss toasts (e.g., ['Escape']). | | ToastWrapper | React.ComponentType<{ children: ReactNode }> | undefined | Custom wrapper component for toast items. |

toast() Options

These options can be passed to any toast method (e.g., toast.success(message, options)).

| Option | Type | Description | | :--- | :--- | :--- | | description | string | Secondary text to display below the title. | | descriptionStyle | TextStyle | Custom text style for the description. | | duration | number | Time in ms before the toast dismisses. Use Infinity for no auto-dismiss. | | position | ToastPosition | Override the position for this specific toast. | | action | { label: string, onClick: () => void } | Action button configuration. | | cancel | { label: string, onClick: () => void } | Cancel button configuration. | | icon | ReactNode | Custom icon for this toast. | | iconColor | string | Custom color for the toast icon. | | backgroundColor | string | Custom background color for the toast. | | textStyle | TextStyle | Custom text style for the title. | | onDismiss | () => void | Callback when the toast is dismissed. | | onAutoClose | () => void | Callback when the toast auto-closes. | | autoDismiss | boolean | Whether the toast should auto-dismiss (default: true, except for custom type). | | dismissible | boolean | Whether the toast can be swiped to dismiss (default: true). | | expandWithSpring | boolean | Use spring animation when expanding toast (default: true). Set to false for timing animation. | | style | ViewStyle | Custom container style. | | className | string | Custom class name (if using NativeWind/Tailwind). | | customBody | ReactNode | Render custom content inside the toast body. |

toast Methods

| Method | Description | | :--- | :--- | | toast.success(message, config?) | Show a success toast with green styling. | | toast.error(message, config?) | Show an error toast with red styling. | | toast.warning(message, config?) | Show a warning toast with amber styling. | | toast.info(message, config?) | Show an info toast with blue styling. | | toast.loading(message, config?) | Show a loading toast with infinite duration and spinner icon. | | toast.custom(message, config?) | Show a custom toast (no auto-dismiss by default). | | toast.promise(promise, messages, config?) | Handle async operations with loading/success/error states. | | toast.dismiss(id?) | Dismiss a specific toast by ID, or all toasts if no ID provided. | | toast.update(id, updates) | Update an existing toast's properties. |

Advanced Usage

Customizing Icons

You can override the default icons globally via the <Toaster /> component or per-toast.

Global Override:

<Toaster
  icons={{
    success: <MyCustomCheckIcon />,
    error: <MyCustomErrorIcon />,
  }}
/>

Per-Toast Override:

toast.success('Saved', {
  icon: <MyCustomIcon />,
  iconColor: '#7C3AED', // Custom icon color
});

Custom Styling

Apply custom styles to toasts for unique appearances.

toast.success('Order Placed', {
  backgroundColor: '#1F2937', // Dark background
  textStyle: { color: '#F9FAFB' }, // Light text
  iconColor: '#10B981', // Custom icon color
});

toast.error('Subscription Cancelled', {
  backgroundColor: '#FEF2F2', // Light red background
  textStyle: { color: '#991B1B' }, // Dark red text
  iconColor: '#991B1B',
});

Keyboard Handling

This library uses react-native-keyboard-controller to smoothly animate toasts out of the way when the keyboard opens. This ensures your toasts are never hidden behind the keyboard, providing a superior user experience compared to standard KeyboardAvoidingView solutions.

Exported Types

The library exports TypeScript types for full type safety:

import type {
  ToastType,
  ToastPosition,
  SwipeDirection,
  ToastConfig,
  ToastMessage,
  ToasterProps,
} from 'goey-native-toast';

Troubleshooting

Toasts are not appearing?

1. Ensure <Toaster /> is rendered at the root of your app.
2. Check if visibleToasts is greater than 0.
3. Verify that react-native-reanimated is properly installed and the babel plugin is added.

Animations are jerky or not working?

1. Ensure you are wrapping your app in <GestureHandlerRootView style={{ flex: 1 }}>.
2. Run npx expo start --clear to clear the bundler cache.
3. If using Expo, make sure you have run npx expo prebuild as this library uses native code.

Contributing

Contributions are welcome! Please see the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT © Teepheh-Git