React Native Toast Message (calintamas/react-native-toast-message)

React Native Toast Message

https://github.com/calintamas/react-native-toast-message
Admin
An animated and customizable toast message component for React Native with an imperative API,...

Tokens:4,344
Snippets:21
Trust Score:8.6
Update:6 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# react-native-toast-message

react-native-toast-message is an animated toast notification component for React Native applications. It provides a lightweight (~40 kB), keyboard-aware solution for displaying temporary notification messages with customizable layouts and positioning. The library uses an imperative API, allowing toasts to be triggered from anywhere in the application, including outside of React components.

The library offers three built-in toast types (success, error, info) with pre-styled layouts, supports custom toast types, and includes features like auto-hide, swipe-to-dismiss gestures, configurable positioning, and lifecycle callbacks. It manages multiple toast instances through a priority-based ref system, automatically using the most recently mounted Toast component, making it compatible with modals and complex view hierarchies.

## Installation and Basic Setup

Install the package and render the Toast component as the last child in your app's root component.

```jsx
// Installation
// npm install react-native-toast-message
// or
// yarn add react-native-toast-message

// App.jsx
import React from 'react';
import { View } from 'react-native';
import Toast from 'react-native-toast-message';

export function App() {
  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}
      <Toast />
    </View>
  );
}
```

## Showing Toast Messages

Display toast notifications imperatively from anywhere in your application using Toast.show() with type, text, and positioning options.

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

export function MyComponent() {
  const showSuccessToast = () => {
    Toast.show({
      type: 'success',
      text1: 'Success',
      text2: 'Your changes have been saved successfully'
    });
  };

  const showErrorToast = () => {
    Toast.show({
      type: 'error',
      text1: 'Error',
      text2: 'Failed to save changes. Please try again.',
      position: 'bottom',
      visibilityTime: 6000,
      autoHide: true,
      topOffset: 30,
      bottomOffset: 40
    });
  };

  const showInfoToast = () => {
    Toast.show({
      type: 'info',
      text1: 'Information',
      text2: 'Processing your request...'
    });
  };

  return (
    <View>
      <Button title="Show Success" onPress={showSuccessToast} />
      <Button title="Show Error" onPress={showErrorToast} />
      <Button title="Show Info" onPress={showInfoToast} />
    </View>
  );
}
```

## Hiding Toast Messages

Manually hide the currently visible toast using Toast.hide().

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

export function ManualControlExample() {
  const showPersistentToast = () => {
    Toast.show({
      type: 'info',
      text1: 'Processing',
      text2: 'Please wait while we process your request...',
      autoHide: false // Toast will not auto-hide
    });
  };

  const hideToast = () => {
    Toast.hide();
  };

  return (
    <View>
      <Button title="Show Persistent Toast" onPress={showPersistentToast} />
      <Button title="Hide Toast" onPress={hideToast} />
    </View>
  );
}
```

## Lifecycle Callbacks

Execute custom logic when toasts are shown, hidden, or pressed using onShow, onHide, and onPress callbacks.

```jsx
import React from 'react';
import { Button, View, Alert } from 'react-native';
import Toast from 'react-native-toast-message';

export function CallbackExample() {
  const showToastWithCallbacks = () => {
    Toast.show({
      type: 'success',
      text1: 'Task Completed',
      text2: 'Tap to view details',
      onShow: () => {
        console.log('Toast is now visible');
      },
      onHide: () => {
        console.log('Toast was hidden');
      },
      onPress: () => {
        Alert.alert('Toast Pressed', 'Navigating to details...');
        Toast.hide();
      }
    });
  };

  return (
    <View>
      <Button title="Show Toast with Callbacks" onPress={showToastWithCallbacks} />
    </View>
  );
}
```

## Custom Toast Configuration

Create custom toast types or override default layouts using the config prop with BaseToast components or completely custom layouts.

```jsx
// App.jsx
import React from 'react';
import { View, Text } from 'react-native';
import Toast, { BaseToast, ErrorToast } from 'react-native-toast-message';

const toastConfig = {
  // Customize the success toast
  success: (props) => (
    <BaseToast
      {...props}
      style={{ borderLeftColor: 'pink' }}
      contentContainerStyle={{ paddingHorizontal: 15 }}
      text1Style={{
        fontSize: 15,
        fontWeight: '400'
      }}
      text2Style={{
        fontSize: 13
      }}
    />
  ),

  // Customize the error toast
  error: (props) => (
    <ErrorToast
      {...props}
      text1Style={{
        fontSize: 17
      }}
      text2Style={{
        fontSize: 15
      }}
    />
  ),

  // Create a completely custom toast type
  customToast: ({ text1, props }) => (
    <View style={{
      height: 60,
      width: '100%',
      backgroundColor: 'tomato',
      padding: 15,
      justifyContent: 'center'
    }}>
      <Text style={{ color: 'white', fontWeight: 'bold' }}>{text1}</Text>
      <Text style={{ color: 'white' }}>{props.message}</Text>
    </View>
  )
};

export function App() {
  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}
      <Toast config={toastConfig} />
    </View>
  );
}

// Using the custom toast type
export function CustomToastExample() {
  const showCustomToast = () => {
    Toast.show({
      type: 'customToast',
      text1: 'Custom Alert',
      props: { message: 'This is a custom styled toast' }
    });
  };

  return (
    <Button title="Show Custom Toast" onPress={showCustomToast} />
  );
}
```

## Default Toast Props

Set default properties for all toasts by passing props to the Toast component instance.

```jsx
// App.jsx
import React from 'react';
import { View } from 'react-native';
import Toast from 'react-native-toast-message';

export function App() {
  const handleToastShow = () => {
    console.log('A toast was shown');
  };

  const handleToastHide = () => {
    console.log('A toast was hidden');
  };

  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}
      <Toast
        position='bottom'
        bottomOffset={20}
        visibilityTime={3000}
        autoHide={true}
        swipeable={true}
        onShow={handleToastShow}
        onHide={handleToastHide}
      />
    </View>
  );
}

// All toasts will now use bottom position by default
export function SomeComponent() {
  const showToast = () => {
    Toast.show({
      type: 'success',
      text1: 'Default position is bottom',
      // Can still override defaults per toast
      position: 'top'
    });
  };

  return <Button title="Show Toast" onPress={showToast} />;
}
```

## Custom Icons and Styling

Extend BaseToast with custom leading and trailing icons plus advanced styling options.

```jsx
import React from 'react';
import { View, Text } from 'react-native';
import Toast, { BaseToast } from 'react-native-toast-message';

const toastConfig = {
  customToastWithIcons: (props) => (
    <BaseToast
      {...props}
      style={{
        borderLeftColor: '#4A90E2',
        borderLeftWidth: 5,
        backgroundColor: '#F0F8FF'
      }}
      contentContainerStyle={{
        paddingHorizontal: 15
      }}
      text1Style={{
        fontSize: 16,
        fontWeight: 'bold',
        color: '#333'
      }}
      text2Style={{
        fontSize: 14,
        color: '#666'
      }}
      text1NumberOfLines={2}
      text2NumberOfLines={3}
      renderLeadingIcon={() => (
        <View style={{
          width: 40,
          height: 40,
          backgroundColor: '#4A90E2',
          borderRadius: 20,
          justifyContent: 'center',
          alignItems: 'center',
          marginLeft: 10
        }}>
          <Text style={{ color: 'white', fontSize: 20 }}>✓</Text>
        </View>
      )}
      renderTrailingIcon={() => (
        <View style={{
          justifyContent: 'center',
          paddingRight: 10
        }}>
          <Text style={{ fontSize: 18 }}>→</Text>
        </View>
      )}
    />
  )
};

export function App() {
  return (
    <View style={{ flex: 1 }}>
      <Toast config={toastConfig} />
    </View>
  );
}

export function IconExample() {
  const showToastWithIcons = () => {
    Toast.show({
      type: 'customToastWithIcons',
      text1: 'Upload Complete',
      text2: 'Your file has been successfully uploaded to the server'
    });
  };

  return <Button title="Show Toast with Icons" onPress={showToastWithIcons} />;
}
```

## Modal Integration

Use multiple Toast instances with priority-based ref management for modals and nested views.

```jsx
import React, { useState } from 'react';
import { View, Modal, Button } from 'react-native';
import Toast from 'react-native-toast-message';

export function App() {
  const [modalVisible, setModalVisible] = useState(false);

  const showAppToast = () => {
    Toast.show({
      type: 'success',
      text1: 'App Toast',
      text2: 'This appears in the main app'
    });
  };

  return (
    <View style={{ flex: 1 }}>
      <Button title="Show App Toast" onPress={showAppToast} />
      <Button title="Open Modal" onPress={() => setModalVisible(true)} />

      <Modal visible={modalVisible} transparent animationType="slide">
        <View style={{
          flex: 1,
          backgroundColor: 'rgba(0,0,0,0.5)',
          justifyContent: 'center',
          padding: 20
        }}>
          <View style={{
            backgroundColor: 'white',
            padding: 20,
            borderRadius: 10
          }}>
            <Button
              title="Show Modal Toast"
              onPress={() => {
                Toast.show({
                  type: 'info',
                  text1: 'Modal Toast',
                  text2: 'This appears inside the modal'
                });
              }}
            />
            <Button
              title="Close Modal"
              onPress={() => setModalVisible(false)}
            />
          </View>
          {/* Toast inside modal has higher priority */}
          <Toast />
        </View>
      </Modal>

      {/* Root toast */}
      <Toast />
    </View>
  );
}
```

## Keyboard Awareness

Configure keyboard offset behavior for bottom-positioned toasts on iOS.

```jsx
import React from 'react';
import { View, Button, TextInput, KeyboardAvoidingView, Platform } from 'react-native';
import Toast from 'react-native-toast-message';

export function App() {
  return (
    <KeyboardAvoidingView
      style={{ flex: 1 }}
      behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
    >
      <View style={{ flex: 1, justifyContent: 'center', padding: 20 }}>
        <TextInput
          placeholder="Type something..."
          style={{
            borderWidth: 1,
            borderColor: '#ccc',
            padding: 10,
            marginBottom: 10
          }}
        />
        <Button
          title="Show Toast"
          onPress={() => {
            Toast.show({
              type: 'success',
              text1: 'Message Sent',
              text2: 'Your message has been delivered',
              position: 'bottom'
            });
          }}
        />
      </View>

      <Toast
        position='bottom'
        bottomOffset={40}
        keyboardOffset={10} // Offset from keyboard when visible (iOS)
        avoidKeyboard={true} // Take keyboard height into account
      />
    </KeyboardAvoidingView>
  );
}
```

## Summary

react-native-toast-message provides a flexible and powerful solution for displaying temporary notifications in React Native applications. The imperative API allows toast messages to be triggered from anywhere in the codebase, while the component-based configuration system enables extensive customization of appearance and behavior. Common use cases include success/error feedback for user actions, informational messages during background operations, form validation errors, and network status notifications.

The library's priority-based ref system makes it ideal for complex applications with modals and nested views, as it automatically determines which Toast instance should display the message. Integration is straightforward - render the Toast component once in your app root, optionally configure custom layouts and defaults, then call Toast.show() from anywhere. The built-in support for gestures, keyboard awareness, positioning, and lifecycle callbacks covers most notification requirements without additional dependencies.