react-native-toast-message

The library uses an internal mechanism to track which <Toast /> instance should respond to imperative calls like Toast.show() or Toast.hide().

When you render <Toast />, a ref is created and tracked automatically. If multiple <Toast /> instances exist (for example, one at the root and one inside a Modal), the library uses the ref from whichever instance was last mounted or had its ref set. This allows seamless switching between the root toast and a modal-specific toast as components mount and unmount.

// App.jsx
import Toast from 'react-native-toast-message'

export function App(props) {
  return (
    <>
      {/* A `ref` pointing to this Toast instance is created and tracked internally */}
      <Toast />
    </>
  );
}

The requirement to render a <Toast /> instance inside the presenting layer applies to react-native-modal and NativeStackNavigator screens using presentation: 'modal'.

To ensure toasts are visible during these presentations, nest a <Toast /> component within the modal or the specific stack screen. The library will automatically use the most recently mounted instance.

<>
  {/* This `Toast` will show when neither the native stack screen nor `Modal` are presented */}
  <Toast />

  <NativeStackNavigator.Screen>
    {/* This `Toast` will show when the `NativeStackNavigator.Screen` is visible, but the `Modal` is NOT visible. */}
    <Toast />

    <Modal>
      {/* This `Toast` will show when both the `NativeStackNavigator.Screen` and the `Modal` are visible. */}
      <Toast />
    </Modal>
  </NativeStackNavigator.Screen>
</>

To prevent actual toast notifications from appearing during your Jest tests and to allow you to assert that toast methods were called, you can mock the react-native-toast-message module. Use jest.mock to provide mock implementations for the show and hide functions.

jest.mock('react-native-toast-message', () => ({
  show: jest.fn(),
  hide: jest.fn()
}));

Install the package using yarn or npm:

yarn add react-native-toast-message
# or
npm install --save react-native-toast-message

To enable toast notifications, you must render the Toast component in your app's entry file. It should be placed as the LAST CHILD in your component hierarchy (alongside other top-level components) to ensure it renders on top of other UI elements.

// App.jsx
import Toast from 'react-native-toast-message';

export function App(props) {
  return (
    <>
      {/* ... other components ... */}
      <Toast />
    </>
  );
}

When using a navigation library like react-navigation, the Toast component must be rendered as the last child in your root component's hierarchy, alongside the NavigationContainer. This ensures the Toast is visible on top of the navigation View hierarchy and is not obscured by screens or navigation elements.

import Toast from 'react-native-toast-message'
import { NavigationContainer } from '@react-navigation/native';

export function App() {
  return (
    <>
      <NavigationContainer>
        {/* ... your navigation stack ... */}
      </NavigationContainer>
      <Toast />
    </>
  );
}

The library manages multiple Toast instances using a priority system based on mounting order. The most recently mounted Toast component (the one highest in the view hierarchy) is considered the 'active' instance.

This is particularly useful when using Modals. If you have a Toast at the App root and another Toast inside a Modal, calling Toast.show() will target the Toast inside the Modal because it was mounted later and sits on top of the view hierarchy.

<>
  <Toast />
  <Modal>
    <Toast />
  </Modal>
</>

To create custom toast appearances, provide a ToastConfig object to the <Toast /> component. The keys in the object correspond to ToastType values, and the values are functions that return a React node.

Each function receives ToastConfigParams, which provides access to the toast's state and data:

• position: Current position.
• type: The toast type.
• isVisible: Boolean indicating if the toast is visible.
• text1 / text2: The content strings.
• show / hide: Functions to programmatically control the toast.
• onPress: The press handler.
• props: Custom properties passed during the .show() call.

export type ToastConfig = {
  [key: string]: (params: ToastConfigParams<any>) => React.ReactNode;
};

To use the library, render the Toast component at the root of your application. The Toast component is designed to be used as a singleton or within specific hierarchies (like Modals) to manage toast notifications.

When multiple Toast components are mounted, the library uses a priority system: the component mounted last (the one highest in the view hierarchy, such as inside a Modal) takes precedence for Toast.show() and Toast.hide() calls.