React Native Toast Message

Common errors

• TypeError: Cannot read property 'show' of undefined

  cause The `Toast` object (imperative API) is not correctly imported or available in the scope where `Toast.show()` is called. This often happens if the import is incorrect or if `Toast` is not rendered at the root level in some setups.
  fix Ensure you are using `import Toast from 'react-native-toast-message';` and that the `<Toast />` component is rendered once at the top level of your React Native application, typically inside your `App.js` or equivalent root component.

• Invariant Violation: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.

  cause This error typically occurs when a React component is imported incorrectly, for example, using named import (`{ Toast }`) when it should be a default import (`Toast`).
  fix Change your import statement for the `Toast` component to use the default export: `import Toast from 'react-native-toast-message';`.

• Toast does not appear or disappears immediately when inside a Modal or Navigation stack.

  cause The `Toast` component needs to be rendered at a sufficiently high level in the component hierarchy (e.g., above the Modal or Navigation container) to ensure it renders on top of all other content.
  fix Follow the specific documentation for 'How to show the Toast inside a Modal?' or 'How to render the Toast when using a Navigation library?' provided in the library's README. Generally, the `<Toast />` component should be placed outside of these elements or inside a dedicated provider/wrapper.

• TypeScript error: Property 'text1' does not exist on type 'ToastOptions' or similar for custom properties.

  cause You are trying to use a custom toast type or extend `ToastOptions` with properties that are not part of the default `ToastOptions` interface without proper type declaration.
  fix If using a custom type, declare it with `type: 'customType'` and ensure you extend `ToastOptions` with your custom props. For example, `declare module 'react-native-toast-message' { export interface ToastOptions { customProp?: string; } }`.

Warnings

• breaking Major API changes occurred during the migration from v1 to v2. Users upgrading from v1 should consult the complete changelog for v2.0.0 to understand necessary adjustments.
  Fix: Review the official v2.0.0 changelog and migration guide on the project's GitHub repository. Adjust component imports, prop names, and API calls accordingly.
• gotcha Toasts with `autoHide: true` could get stuck when panned or swiped, leading to a persistent toast on screen.
  Fix: Update to version `2.3.2` or higher to resolve the issue where toasts would get stuck when panned. If unable to update, consider disabling swipeable gestures with `swipeable: false`.
• gotcha On iOS, toasts might not position correctly when the keyboard is open, appearing behind or incorrectly aligned with input fields.
  Fix: Upgrade to version `2.3.0` or newer, which includes a fix for toast positioning issues on iOS when the keyboard is active. Ensure your `Toast` component is rendered at a high enough level in the component tree.
• gotcha Swipeable gestures for dismissing toasts are enabled by default since v2.2.0. This might conflict with other gestures or be undesired in some UX flows.
  Fix: To disable swipeable dismissal, pass the `swipeable: false` option to `Toast.show()` or within your custom toast configuration. For example: `Toast.show({ ..., swipeable: false })`.
• gotcha Compatibility issues with React 19 were reported, specifically related to return types for base toast components.
  Fix: Ensure you are using `react-native-toast-message` version `2.3.3` or higher for full compatibility with React 19. If you encounter type errors related to `BaseToast`, `SuccessToast`, `InfoToast`, or `ErrorToast` return types, updating the package will resolve them.

Install

• npm install react-native-toast-message npm
• yarn add react-native-toast-message yarn
• pnpm add react-native-toast-message pnpm

Imports

• Toast (component & API)
  wrong:

  import { Toast } from 'react-native-toast-message';

  correct:

  import Toast from 'react-native-toast-message';

  The library's main component and imperative API are exposed as a default export. Both `<Toast />` and `Toast.show()` use this single import.
• ToastProps
  wrong:

  import { ToastOptions } from 'react-native-toast-message';

  correct:

  import type { ToastOptions } from 'react-native-toast-message';

  Use `import type` for type-only imports in TypeScript to ensure better tree-shaking and module resolution, especially in hybrid ESM/CJS environments.
• BaseToast, SuccessToast, ErrorToast, InfoToast
  wrong:

  import BaseToast from 'react-native-toast-message/BaseToast';

  correct:

  import { BaseToast, SuccessToast } from 'react-native-toast-message';

  Customizable toast types are named exports. Direct path imports might not be tree-shakable or could break in future versions.

Quickstart

This quickstart demonstrates rendering the `Toast` component at the root of your application and using the imperative `Toast.show()` method to display success and error messages.

import React from 'react';
import { Button, View, StyleSheet, SafeAreaView } from 'react-native';
import Toast from 'react-native-toast-message';

const App = () => {
  const showSuccessToast = () => {
    Toast.show({
      type: 'success',
      text1: 'Success!',
      text2: 'Your operation was completed successfully.',
      visibilityTime: 3000,
      autoHide: true,
      topOffset: 30
    });
  };

  const showErrorToast = () => {
    Toast.show({
      type: 'error',
      text1: 'Error!',
      text2: 'Failed to perform operation. Please try again.',
      visibilityTime: 4000,
      autoHide: true
    });
  };

  return (
    <SafeAreaView style={styles.safeArea}>
      <View style={styles.container}>
        <Button title="Show Success Toast" onPress={showSuccessToast} />
        <View style={styles.spacer} />
        <Button title="Show Error Toast" onPress={showErrorToast} />
        <Toast />
      </View>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  safeArea: {
    flex: 1,
  },
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#F5FCFF',
  },
  spacer: {
    height: 20,
  },
});

export default App;