react-native-hot-toast
TypeScript icon, indicating that this package has built-in type declarations

0.9.2 • Public • Published

React Native Hot Toast

A toast library for react-native, built on react-hot-toast. It supports features such as multiple toasts, keyboard handling, swipe to dismiss, positional toasts, and JS promises. It runs on iOS, android, and web. this is the fork of React Native Toast to support dependencies


video


Why?

I know what you might be thinking (jeez, another toast library?). Trust me here, this is the last toast library you will need. I built this library to meet my specific app needs and decided to open-source it after realizing that it truly is a top-notch toast library. Just give it a try.

Features

  • Multiple toasts, multiple options. Want a toast on the top, bottom, different colors, or different types at the same time? Got it.
  • Keyboard handling (both iOS and Android). Move those toasts out of the way and into view when the user opens the keyboard
  • Swipe to dismiss
  • Positional toasts (top & bottom)
  • Customizable (custom styles, dimensions, duration, and even create your own component to be used in the toast)
  • Add support for promises <-- Really! Call toast.promise(my_promise) and watch react-native-hot-toast work its magic, automatically updating the toast with a custom message on success -- or an error message on reject.
  • Runs on web
  • Support for native modals
  • Callbacks for onPress, onShow, and onHide

Getting Started

Installation

Check in npm

Peer Dependencies

Install and link react-native-reanimated, react-native-safe-area-context, and react-native-gesture-handler

yarn add react-native-reanimated react-native-safe-area-context react-native-gesture-handler

Ensure you follow the installation of each package

Using expo?

expo install react-native-reanimated react-native-safe-area-context react-native-gesture-handler

Cool, now what?

Add the <Toasts /> component into the root of your app. Whenever you are ready, call toast("My Toast Message") from anywhere in your app.

import { StyleSheet, Text } from 'react-native';
import { toast, Toasts } from '@oushdr/react-native-hot-toast';
import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    toast('Hello');
  }, []);

  return (
    <View style={styles.container}>
      <View>{/*The rest of your app*/}</View>
      <Toasts /> {/* <---- Add Here */}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

Example

Regular Toast

toast("This is my first toast", {
  duration: 3000,
});

Promise Toast

const sleep = new Promise((resolve, reject) => {
  setTimeout(() => {
    if (Math.random() > 0.5) {
      resolve({
        username: 'Nick',
      });
    } else {
      reject('Username is undefined');
    }
  }, 2500);
});

toast.promise(
  sleep,
  {
    loading: 'Loading...',
    success: (data: any) => 'Welcome ' + data.username,
    error: (err) => err.toString(),
  },
  {
    position: ToastPosition.BOTTOM,
  }
);

Loading Toast

const id = toast.loading('I am loading. Dismiss me whenever...');

setTimeout(() => {
  toast.dismiss(id);
}, 3000);

Success Toast

toast.success('Success!', {
  width: 300
});

Error Toast

toast.error('Wow. That Sucked!');

Documentation

<Toasts />

Include the <Toasts /> component in the root of your app.

Props

overrideDarkMode (boolean | undefined) (optional)

Override the system dark mode. If a value is supplied (I.e. true or false), then the toast components will use that value for the dark mode. For example, if overrideDarkMode = {false}, dark mode will be disabled, regardless of the system's preferences.

extraInsets (object) (optional)

Supply the container for the toasts extra padding.

extraInsets?: {
  top?: number;
  bottom?: number;
  right?: number;
  left?: number;
};

onToastShow (function) (optional)

When a toast is shown, this callback will fire, returning the toast object that was shown. Note, the toast object is "shown" when the toast is mounted.

onToastShow?: (toast: T) => void;

onToastHide (function) (optional)

When a toast is hidden, this callback will fire, returning the toast object that was hidden. Note, the toast object is "hidden" when the toast is unmounted.

onToastHide?: (toast: T) => void;

onToastPress (function) (optional)

When a toast is pressed, this callback will fire, returning the toast object that was pressed.

onToastPress?: (toast: T) => void;

providerKey (string) (optional)

Provide the Toasts component with a providerKey to conditionally render toasts in a component. Useful for rendering toasts in native modals.

// Component in native modal
<Toasts providerKey="MODAL::1" />

//...
// Root component
<Toasts /> //has default providerKey of DEFAULT

//...
// Call toast in root modal

const id = toast("Hello from root modal") //default providerKey of DEFAULT

// Native modal becomes visible
const id = toast("Hello from native modal", {providerKey: "MODAL::1"})
//Now, toast is shown only in native modal

If you want to persist toasts across components (i.e. when you open/close a modal and want to keep the same toasts), your toasts should be assigned a providerKey of "PERSISTS".

toast("Message...", {providerKey: "PERSISTS"})

Or, if you cannot do so, you can update each toast manually.

const { toasts } = useToasterStore(); //Note, no provider key passed in

useEffect(() => {
  toasts.forEach((t) => {
    toast(t.message, {
      ...t,
      providerKey: isModalVisible ? 'MODAL::1' : 'DEFAULT', //Switch provider key here
    });
  });
}, [isModalVisible]);

Example

<Toasts
  onToastPress={(t) => {
    console.log(`Toast ${t.id} was pressed.`)
  }}
  overrideDarkMode={isAppDarkMode}
/>

toast() API

Call it to create a toast from anywhere, even outside React (hello errors from controllers). Make sure you add the <Toasts/>component to your app first.

Available toast options

You can provide ToastOptions as the second argument. All arguments are optional.

toast('Hello World', {
  duration: 4000,
  position: ToastPosition.TOP,
  icon: '👏',
  styles: {
    view: ViewStyle,
    pressable: ViewStyle,
    text: TextStyle,
    indicator: ViewStyle
  },
});

Creating a toast

Blank

toast('Hello World');

The most basic variant.

Success

toast.success('Successfully created!');

Creates a notification with a success indicator on the left.

Error

toast.error('This is an error!');

Creates a notification with an error indicator on the left.

Custom (JSX)

toast("", {
  customToast: (toast) => (
    <View>
      <Text>{toast.message}</Text>
    </View>
   )
})

Creates a custom notification with JSX. Have complete control over your toast.

Full example

toast(Math.floor(Math.random() * 1000).toString(), {
  width: screenWidth,
  disableShadow: true,
  customToast: (toast) => {
    return (
      <View
        style={{
          height: toast.height,
          width: toast.width,
          backgroundColor: 'yellow',
          borderRadius: 8,
        }}
      >
        <Text>{toast.message}</Text>
      </View>
    );
  },
});

Loading

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

//Somewhere later in your code...

toast.dismiss(id);

This will create a loading notification. Most likely, you want to update it afterwards. For a friendly alternative, check out toast.promise(), which takes care of that automatically.

Promise

This shorthand is useful for mapping a promise to a toast. It will update automatically when the promise resolves or fails.

Simple Usage

const myPromise = fetchData();

toast.promise(myPromise, {
  loading: 'Loading',
  success: 'Got the data',
  error: 'Error when fetching',
});

Advanced

You can provide a function to the success/error messages to incorporate the result/error of the promise. The third argument is toastOptions.

toast.promise(
  myPromise,
  {
    loading: 'Loading',
    success: (data) => `Successfully saved ${data.name}`,
    error: (err) => `This just happened: ${err.toString()}`,
  },
  {
    duration: 2000
  }
);

Default durations

Every type has its own duration. You can overwrite them duration with the toast options.

type duration
blank 4000
error 4000
success 2000
custom 4000
loading Infinity

Dismiss toast programmatically

You can manually dismiss a notification with toast.dismiss. Be aware that it triggers the exit animation and does not remove the Toast instantly. Toasts will auto-remove after 1 second by default.

Dismiss a single toast

const toastId = toast('Loading...');

// ...

toast.dismiss(toastId);

You can dismiss all toasts at once, by leaving out the toastId.

Dismiss all toasts at once

toast.dismiss();

To remove toasts instantly without any animations, use toast.remove.

Remove toasts instantly

toast.remove(toastId);

// or

toast.remove();

Update an existing toast

Each toast call returns a unique id. Use in the toast options to update the existing toast.

const toastId = toast.loading('Loading...');

// ...

toast.success('This worked', {
  id: toastId,
});

Prevent duplicate toasts

To prevent duplicates of the same kind, you can provide a unique permanent id.

toast.success('Copied to clipboard!', {
  id: 'clipboard',
});

ToastOptions all optional

Option Name Type Possible Values
id string Given an id, update the toast with the following options
message string The message to render in the toast
position ToastPosition.TOP, ToastPosition.BOTTOM, number The position of the toast. Use the ToastPosition enum to effectively set it
duration number the duration (in ms) to show the toast for
customToast function override the toast body and apply a custom toast. Receives the toast as a parameter I.e. (toast: Toast) => JSX.Element
height number the height of the toast Must set here even if you are using a custom toast or applying it in the styles.view/pressable to ensure calculations are accurate
width number the width of the toast
icon JSX.Element, string Render an icon to the left of the message
styles object the styles to apply to the toast
disableShadow boolean Disable the shadow underneath the toast

Styles object

{
  pressable?: ViewStyle;
  view?: ViewStyle;
  text?: TextStyle;
  indicator?: ViewStyle;
};

Thank you react-hot-toast

react-native-hot-toast is built with modified react-hot-toast internals? Why? Well, react-native doesn't really need all the unnecessary web fluff (aria what?). So, I trimmed it down and made it perfect for mobile development by battle testing it on mobile devices and creating react-native components built specifically for iOS and Android development.


Author

Ousmane HAIDARA on LinkedIn


Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library

Package Sidebar

Install

npm i react-native-hot-toast

Weekly Downloads

1

Version

0.9.2

License

MIT

Unpacked Size

209 kB

Total Files

87

Last publish

Collaborators

  • oushdr