# 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 (
{/* Your app content */}
);
}
```
## 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 (
);
}
```
## 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 (
);
}
```
## 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 (
);
}
```
## 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) => (
),
// Customize the error toast
error: (props) => (
),
// Create a completely custom toast type
customToast: ({ text1, props }) => (
{text1}{props.message}
)
};
export function App() {
return (
{/* Your app content */}
);
}
// 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 (
);
}
```
## 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 (
{/* Your app content */}
);
}
// 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 ;
}
```
## 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) => (
(
✓
)}
renderTrailingIcon={() => (
→
)}
/>
)
};
export function App() {
return (
);
}
export function IconExample() {
const showToastWithIcons = () => {
Toast.show({
type: 'customToastWithIcons',
text1: 'Upload Complete',
text2: 'Your file has been successfully uploaded to the server'
});
};
return ;
}
```
## 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 (
);
}
```
## 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 (
);
}
```
## 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.