React Native Flash Message

Common errors

• TypeError: Cannot read property 'showMessage' of undefined

  cause The `showMessage` function was called without an instantiated global `FlashMessage` component, or it was not imported correctly.
  fix Ensure `import { showMessage } from 'react-native-flash-message';` is present and that a `<FlashMessage />` component is rendered as the last child in your root component tree.

• Error: `message` attribute is required for FlashMessage

  cause The object passed to the `showMessage` function is missing the mandatory `message` property.
  fix Add a `message` string property to the object you pass to `showMessage`, for example: `showMessage({ message: 'Your notification text here', type: 'info' })`.

• Flash messages are not appearing or are obscured by other UI elements.

  cause The `FlashMessage` component is not placed as the last child in the main application's render tree or within its intended parent `View` component.
  fix Move the `<FlashMessage />` component to be the absolute last element rendered within your root `View` component in your `App.js`/`App.tsx` file.

Warnings

• breaking In version `0.4.0`, the internal dependency for iPhone notch and safe area detection was changed from the unmaintained `react-native-iphone-x-helper` to `react-native-iphone-screen-helper`. While this is primarily an internal change, projects with existing, specific workarounds or other dependencies relying on the older helper might experience subtle layout regressions on notch devices if not properly updated.
  Fix: Ensure all related dependencies are updated to their latest compatible versions. If upgrading from older versions, thoroughly test UI layouts on various notch devices to detect any unexpected visual issues.
• gotcha The `FlashMessage` component *must* be rendered as the very last child within its parent `View` to ensure it correctly overlays all other content and is fully visible. Incorrect placement will often lead to messages being obscured by other UI elements.
  Fix: Always place the `<FlashMessage position='top' />` (or other position) component at the absolute end of your main `App` component's render tree, or as the last child of the specific `View` it is intended to cover.
• gotcha When calling the `showMessage` function, the message object passed as an argument *must* include a `message` property with a string value. Omitting this required property will result in an error or an empty flash message failing to display.
  Fix: Always provide a `message` string property in the object passed to `showMessage`, for example: `showMessage({ message: 'Your notification text', type: 'info' })`.
• gotcha For local `FlashMessage` instances scoped to a specific screen or component (instead of global), the `FlashMessage` component must be rendered with a `ref` prop. This allows you to call `showMessage` directly on that specific instance via the ref.
  Fix: If you need a local message instance, render it as `<FlashMessage ref={myRef} />` and then call `myRef.current.showMessage(...)` on the ref. Global instances do not require a ref and rely on the exported `showMessage` helper function.

Install

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

Imports

• FlashMessage
  wrong:

  import { FlashMessage } from 'react-native-flash-message';

  correct:

  import FlashMessage from 'react-native-flash-message';

  The main `FlashMessage` component is a default export and should be imported without curly braces.
• showMessage
  wrong:

  import showMessage from 'react-native-flash-message';

  correct:

  import { showMessage } from 'react-native-flash-message';

  The `showMessage` utility function for programmatically displaying messages is a named export and must be destructured.
• hideMessage
  wrong:

  import hideMessage from 'react-native-flash-message';

  correct:

  import { hideMessage } from 'react-native-flash-message';

  The `hideMessage` utility function is a named export and must be destructured.

Quickstart

This example demonstrates how to integrate `FlashMessage` globally and trigger messages using `showMessage` with different types and positions.

import React from "react";
import { View, Button, StyleSheet, Text } from "react-native";
import FlashMessage, { showMessage } from "react-native-flash-message";

function App() {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>React Native Flash Message Demo</Text>
      <Button
        title="Show Info Message"
        onPress={() => {
          showMessage({
            message: "Hello from Flash Message!",
            description: "This is an example info message.",
            type: "info",
            duration: 3000,
            icon: "success"
          });
        }}
      />
      <View style={{ height: 20 }} />
      <Button
        title="Show Error Message"
        color="red"
        onPress={() => {
          showMessage({
            message: "Something went wrong!",
            description: "Please check your network connection and try again.",
            type: "danger",
            duration: 5000,
            icon: "danger",
            position: "bottom"
          });
        }}
      />
      {/* GLOBAL FLASH MESSAGE COMPONENT INSTANCE - MUST BE THE LAST COMPONENT */}
      {/* This component acts as the container for all flash messages. */}
      {/* It should be placed at the root level of your app, as the very last child. */}
      <FlashMessage position="top" />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    padding: 20,
    backgroundColor: "#f0f0f0"
  },
  title: {
    fontSize: 22,
    fontWeight: "bold",
    marginBottom: 40,
    textAlign: "center"
  }
});

export default App;