toastify-react-native

toastify-react-native

🎉 toastify-react-native allows you to add notifications to your React Native app (iOS, Android) with ease. No more nonsense!

Table of Contents

• Demo
• Features
• Installation
• Basic Usage
• Advanced Usage
• Modal Behavior 👈 NEW
• Available Props
• Custom Components
• Customizing Icons
• API Reference
• Upgrading from v6.x
• Contributing
• License

Demo

View examples on snack.expo.io

Features

• 🚀 Simple API: Easy to use with minimal setup
• 🎨 Highly customizable: Customize colors, icons, animations, and more
• 🧩 Custom components: Create your own toast components
• 🎭 Custom icons: Use different icon families, custom icon components, or JSX elements
• 📱 Responsive: Adapts to different screen sizes
• 🌓 Dark & Light mode: Built-in theme support
• 🔄 RTL support: Right-to-left language support
• ⏱️ Progress bar: Visual indicator of toast duration
• 🖐️ Interactive: Pause on touch, resume on release
• 🔄 Animation options: Choose from different animation styles
• 📝 Multiple lines: Support for title and description
• 🔍 TypeScript support: Full type definitions included
• ✨ Smooth animations: Beautiful enter/exit animations
• ⚡ Quick setup: Get up and running in less than 10 seconds!
• 🎛️ Per-toast behavior: Define different behaviors for each toast
• 📊 Progress control: Control the progress bar like nprogress
• 🔧 Super easy to customize: Modify every aspect to match your app's design
• 🎭 And much more!: Discover all the possibilities!

Installation

npm install toastify-react-native
# or
yarn add toastify-react-native

Required Dependencies

This package requires react-native-vector-icons:

npm install react-native-vector-icons
# or
yarn add react-native-vector-icons

Follow the react-native-vector-icons installation guide to complete the setup for your platform.

Basic Usage

import React from 'react'
import { View, Button } from 'react-native'
import ToastManager, { Toast } from 'toastify-react-native'

export default function App() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button
        title='Show Success Toast'
        onPress={() => {
          Toast.success('Success message!')
        }}
      />

      <Button
        title='Show Error Toast'
        onPress={() => {
          Toast.error('Error message!')
        }}
      />

      <Button
        title='Show Info Toast'
        onPress={() => {
          Toast.info('Info message!')
        }}
      />

      <Button
        title='Show Warning Toast'
        onPress={() => {
          Toast.warn('Warning message!')
        }}
      />

      {/* Toast provider should be at the root level */}
      <ToastManager />
    </View>
  )
}

Advanced Usage

Custom Configuration

import React from 'react'
import { View, Button, Text } from 'react-native'
import ToastManager, { Toast } from 'toastify-react-native'

// Custom toast configuration
const toastConfig = {
  success: (props) => (
    <View style={{ backgroundColor: '#4CAF50', padding: 16, borderRadius: 10 }}>
      <Text style={{ color: 'white', fontWeight: 'bold' }}>{props.text1}</Text>
      {props.text2 && <Text style={{ color: 'white' }}>{props.text2}</Text>}
    </View>
  ),
  // Override other toast types as needed
}

export default function App() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button
        title='Show Custom Toast'
        onPress={() => {
          Toast.show({
            type: 'success',
            text1: 'Main message',
            text2: 'Secondary message',
            position: 'bottom',
            visibilityTime: 4000,
            autoHide: true,
            onPress: () => console.log('Toast pressed'),
            onShow: () => console.log('Toast shown'),
            onHide: () => console.log('Toast hidden'),
          })
        }}
      />

      {/* Toast provider with custom config */}
      <ToastManager config={toastConfig} />
    </View>
  )
}

Toast Positions

Toast.success('Top toast', 'top') // default
Toast.error('Center toast', 'center')
Toast.info('Bottom toast', 'bottom')

Customizing Individual Toasts

Toast.show({
  type: 'success',
  text1: 'Custom Toast',
  text2: 'With many options',
  position: 'bottom',
  visibilityTime: 5000,
  autoHide: true,
  backgroundColor: '#333',
  textColor: '#fff',
  iconColor: '#4CAF50',
  iconSize: 24,
  progressBarColor: '#4CAF50',
  theme: 'dark',
})

Modal Behavior

The useModal prop controls whether the toast uses a modal overlay that blocks interaction with the background screen. This is particularly important when working with modals in your app.

Why is this important?

• With Modal (useModal: true): The toast appears with a modal overlay, making the background screen non-interactive. This ensures the toast is always visible, even over other modals, but prevents users from interacting with content behind it.

• Without Modal (useModal: false): The toast appears without blocking interaction with the background screen. Users can still interact with your app while the toast is displayed, but the toast might not appear over other modal components.

Usage Examples

Setting at ToastManager level (affects all toasts)

// All toasts will use modal behavior by default
<ToastManager useModal={true} />

// All toasts will NOT use modal behavior by default
<ToastManager useModal={false} />

Setting for individual toasts with Toast.show()

// This toast will use modal behavior
Toast.show({
  type: 'success',
  text1: 'Using Modal',
  text2: 'Background is not interactive',
  useModal: true,
})

// This toast will NOT use modal behavior
Toast.show({
  type: 'error',
  text1: 'No Modal',
  text2: 'Background remains interactive',
  useModal: false,
})

Using with shorthand methods

// Success toast with modal behavior
Toast.success(
  'Success with Modal!',
  'bottom', // position
  undefined, // icon
  undefined, // iconFamily
  true, // useModal
)

// Error toast without modal behavior
Toast.error(
  'Error without Modal!',
  'bottom', // position
  undefined, // icon
  undefined, // iconFamily
  false, // useModal
)

Conditional usage based on context

// Inside a modal component
const showToastInModal = () => {
  Toast.show({
    type: 'info',
    text1: 'Modal Context',
    text2: 'This toast appears over the modal',
    useModal: true, // Ensure it appears over the modal
  })
}

// In regular app context
const showRegularToast = () => {
  Toast.show({
    type: 'success',
    text1: 'Regular Context',
    text2: 'Allow interaction with the app',
    useModal: false, // Allow background interaction
  })
}

Available Props

ToastManager Props

Prop	Type	Default	Description
width	number | string | 'auto'	'90%'	Width of the toast
minHeight	number | string | 'auto'	61	Minimum height of the toast
style	StyleProp	{}	Custom style for the toast container
textStyle	StyleProp	{}	Custom style for the toast text
theme	'light' | 'dark'	'light'	Theme of the toast
animationStyle	'none' | 'slide' | 'fade'	'fade'	Animation style for the toast
position	'top' | 'center' | 'bottom'	'top'	Position of the toast
duration	number	3000	Duration in ms before the toast disappears
showCloseIcon	boolean	true	Whether to show the close icon
showProgressBar	boolean	true	Whether to show the progress bar
isRTL	boolean	false	Right-to-left support
topOffset	number	40	Distance from the top when position is 'top'
bottomOffset	number	40	Distance from the bottom when position is 'bottom'
iconSize	number	22	Size of the icon
iconFamily	string	'Ionicons'	Default icon family to use
icons	object	undefined	Custom default icons for each toast type
config	ToastConfig	undefined	Custom toast components configuration
useModal	boolean	true	Whether to use modal overlay for toasts

Toast.show() Options

Option	Type	Default	Description
type	'success' | 'error' | 'info' | 'warn' | 'default'	'default'	Type of toast
text1	string	''	Main text
text2	string	undefined	Secondary text
position	'top' | 'center' | 'bottom'	'top'	Position of the toast
visibilityTime	number	3000	Duration in ms before the toast disappears
autoHide	boolean	true	Whether the toast should hide automatically
onShow	() => void	undefined	Callback when toast is shown
onHide	() => void	undefined	Callback when toast is hidden
onPress	() => void	undefined	Callback when toast is pressed
progressBarColor	string	undefined	Color of the progress bar
backgroundColor	string	undefined	Background color of the toast
textColor	string	undefined	Color of the text
icon	string | ReactNode	undefined	Custom icon name or component
iconFamily	string	undefined	Icon family for the icon
iconColor	string	undefined	Color of the icon
iconSize	number	undefined	Size of the icon
theme	'light' | 'dark'	undefined	Theme of the toast
useModal	boolean	undefined	Whether to use modal overlay for this toast

Custom Components

You can create your own toast components by providing a custom configuration:

import React from 'react'
import { View, Text, StyleSheet } from 'react-native'
import ToastManager, { Toast } from 'toastify-react-native'
import Icon from 'react-native-vector-icons/MaterialIcons'

const CustomToast = ({ text1, text2, hide }) => {
  return (
    <View style={styles.customToast}>
      <Icon name='star' size={24} color='#FFD700' />
      <View style={styles.textContainer}>
        <Text style={styles.title}>{text1}</Text>
        {text2 && <Text style={styles.message}>{text2}</Text>}
      </View>
      <Icon name='close' size={20} color='#fff' onPress={hide} />
    </View>
  )
}

const styles = StyleSheet.create({
  customToast: {
    width: '90%',
    backgroundColor: '#673AB7',
    borderRadius: 10,
    padding: 16,
    flexDirection: 'row',
    alignItems: 'center',
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.25,
    shadowRadius: 3.84,
    elevation: 5,
  },
  textContainer: {
    flex: 1,
    marginLeft: 12,
  },
  title: {
    color: '#fff',
    fontWeight: 'bold',
    fontSize: 16,
  },
  message: {
    color: '#fff',
    fontSize: 14,
    marginTop: 4,
  },
})

export default function App() {
  const toastConfig = {
    custom: (props) => <CustomToast {...props} />,
  }

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button
        title='Show Custom Toast'
        onPress={() => {
          Toast.show({
            type: 'custom',
            text1: 'Custom Component',
            text2: 'This is a fully custom toast component!',
          })
        }}
      />

      <ToastManager config={toastConfig} />
    </View>
  )
}

Customizing Icons

// Different icon name from the default family
Toast.show({
  type: 'success',
  text1: 'Different Icon',
  text2: 'Using a different icon name',
  icon: 'check', // Different icon name according to default icon family
})

// Using a different icon family
Toast.show({
  type: 'error',
  text1: 'FontAwesome Icon',
  text2: 'Using a different icon family',
  icon: 'exclamation-circle',
  iconFamily: 'FontAwesome',
})

// Using a custom React component as icon
const CustomIcon = ({ color }) => (
  <View
    style={{
      width: 30,
      height: 30,
      borderRadius: 15,
      backgroundColor: color || '#4CAF50',
      alignItems: 'center',
      justifyContent: 'center',
    }}
  >
    <FontAwesome name='check' size={18} color='#FFFFFF' />
  </View>
)

Toast.show({
  type: 'info',
  text1: 'Custom Component',
  text2: 'Using a custom React component as icon',
  icon: <CustomIcon color='#3498db' />,
})

// Using JSX directly as icon
Toast.show({
  type: 'success',
  text1: 'JSX Icon',
  text2: 'Using JSX directly as icon',
  icon: (
    <View style={{ flexDirection: 'row' }}>
      <FontAwesome name='thumbs-up' size={22} color='#4CAF50' />
      <FontAwesome
        name='thumbs-up'
        size={22}
        color='#4CAF50'
        style={{ marginLeft: -8, marginTop: 5 }}
      />
    </View>
  ),
})

// Setting default icons at the ToastManager level
<ToastManager
  config={toastConfig}
  theme='light'
  position='top'
  // Custom default icons configuration
  icons={{
    success: 'check-circle',
    error: 'error',
    info: 'info',
    warn: 'warning',
    default: 'notifications',
  }}
  // Default icon family
  iconFamily='MaterialIcons'
  // Default icon size
  iconSize={24}
/>

API Reference

Toast Functions

• Toast.show(options): Show a toast with custom options
• Toast.success(message, position?, icon?, iconFamily?, useModal?): Show a success toast
• Toast.error(message, position?, icon?, iconFamily?, useModal?): Show an error toast
• Toast.info(message, position?, icon?, iconFamily?, useModal?): Show an info toast
• Toast.warn(message, position?, icon?, iconFamily?, useModal?): Show a warning toast
• Toast.hide(): Hide the current toast

Upgrading from v6.x

If you're upgrading from version 6.x, please note the following changes:

• The animation system has been simplified to use React Native's built-in Modal animations
• Some props have been removed or renamed for clarity
• The styling system has been improved for better customization
• Custom components now receive more props for better control

For users of v6.x and below, refer to the legacy documentation.

Contributing

We welcome contributions to make toastify-react-native even better!

• Check out our contribution guidelines for details on the process
• Have questions? Open an issue or join the discussion
• Found a bug? Submit a pull request
• Have a feature request? Open an issue

Thank you to all our contributors!

License

toastify-react-native is MIT licensed.