Skip to main content

​
Quickstart

This guide will get you from zero to showing toasts in just a few minutes.
Make sure you’ve completed the installation steps before continuing.

​
Add the BreadLoaf component

The BreadLoaf component manages and displays all toasts. Add it once to your app’s root component.
1

Standard React Native app

Add BreadLoaf to your App.tsx or root component:
App.tsx
import { BreadLoaf } from 'react-native-bread';
import { View } from 'react-native';
import { NavigationContainer } from '@react-navigation/native';

function App() {
  return (
    <View style={{ flex: 1 }}>
      <NavigationContainer>
        {/* Your navigation */}
      </NavigationContainer>
      <BreadLoaf />
    </View>
  );
}

export default App;
Place BreadLoaf after your navigation container so toasts appear above all screens.
2

Expo Router

Add BreadLoaf to your root layout file (app/_layout.tsx):
app/_layout.tsx
import { BreadLoaf } from 'react-native-bread';
import { Stack } from 'expo-router';

export default function RootLayout() {
  return (
    <>
      <Stack>
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
        <Stack.Screen name="+not-found" />
      </Stack>
      <BreadLoaf />
    </>
  );
}
This ensures toasts display across all screens in your app.

​
Show your first toast

Now you can show toasts from anywhere in your app using the toast API: 
import { toast } from 'react-native-bread';
import { Button, View } from 'react-native';

export default function MyScreen() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button
        title="Show toast"
        onPress={() => toast.success('Hello!', 'Your first toast')}
      />
    </View>
  );
}
That’s it! Press the button and you’ll see a success toast with a green checkmark.

​
Toast types

React Native Bread supports multiple toast types, each with its own icon and color scheme: 
toast.success('Saved!', 'Your changes have been saved');

​
Promise toasts

Promise toasts are perfect for tracking async operations. They automatically transition from loading → success or loading → error: 
import { toast } from 'react-native-bread';

async function saveSettings(data: Settings) {
  const result = await toast.promise(
    api.updateSettings(data),
    {
      loading: { 
        title: 'Saving...', 
        description: 'Updating your settings' 
      },
      success: { 
        title: 'Saved!', 
        description: 'Your settings have been updated' 
      },
      error: (err) => ({ 
        title: 'Save failed', 
        description: err.message 
      }),
    }
  );

  if (result.success) {
    console.log('Settings saved:', result.data);
  } else {
    console.error('Error:', result.error);
  }
}

​
Customize individual toasts

You can customize each toast by passing an options object: 
toast.success('Saved!', {
  description: 'Your changes have been saved',
  duration: 5000, // Show for 5 seconds
  dismissible: true, // Allow swipe to dismiss
  showCloseButton: true, // Show X button
  style: { backgroundColor: '#fff' },
  titleStyle: { fontWeight: '600' },
});

​
Available options

  • duration - Display time in milliseconds (default: 4000)
  • description - Secondary text below the title
  • icon - Custom icon component or render function
  • style - ViewStyle for the toast container
  • titleStyle - TextStyle for the title
  • descriptionStyle - TextStyle for the description
  • dismissible - Enable/disable swipe to dismiss
  • showCloseButton - Show/hide the close button
  • deduplication - Enable/disable deduplication for this toast
  • id - Stable ID for deduplication and updates

​
Custom toasts

For complete control over the toast appearance, use toast.custom() with your own component: 
import { toast } from 'react-native-bread';
import { View, Text, Image, Pressable } from 'react-native';

function showNotification() {
  toast.custom(({ dismiss }) => (
    <View style={{ 
      padding: 16, 
      flexDirection: 'row', 
      alignItems: 'center',
      gap: 12,
      backgroundColor: '#fff',
      borderRadius: 12,
    }}>
      <Image 
        source={{ uri: 'https://example.com/avatar.png' }} 
        style={{ width: 44, height: 44, borderRadius: 22 }} 
      />
      <View style={{ flex: 1 }}>
        <Text style={{ fontWeight: '600', fontSize: 16 }}>New message</Text>
        <Text style={{ color: '#666', fontSize: 14 }}>Hey, check this out!</Text>
      </View>
      <Pressable onPress={dismiss}>
        <Text style={{ color: '#3b82f6', fontWeight: '500' }}>Reply</Text>
      </Pressable>
    </View>
  ));
}
Your custom component receives:
  • id - The toast ID
  • dismiss - Function to dismiss this toast
  • type - The toast type
  • isExiting - Whether the toast is currently exiting

​
Global configuration

Customize default behavior for all toasts via the config prop on BreadLoaf: 
<BreadLoaf
  config={{
    position: 'bottom', // 'top' | 'bottom'
    stacking: true, // Show multiple toasts
    maxStack: 3, // Max visible toasts
    defaultDuration: 4000, // Default display time
    dismissible: true, // Allow swipe to dismiss
    showCloseButton: true, // Show X button
    deduplication: true, // Prevent duplicate toasts
    colors: {
      success: { 
        accent: '#22c55e', 
        background: '#f0fdf4' 
      },
      error: { 
        accent: '#ef4444', 
        background: '#fef2f2' 
      },
    },
  }}
/>

​
Configuration options

Where toasts appear on screen: 'top' or 'bottom' (default: 'top')
Extra spacing from screen edge in pixels, added to safe area insets (default: 0)
Show multiple toasts stacked (default: true). When false, only one toast shows at a time.
Maximum number of toasts visible at once when stacking is enabled (default: 3)
Allow toasts to be dismissed via swipe gesture (default: true)
Show the X button on toasts (default: true). Loading toasts never show the close button.
Default display time in milliseconds (default: 4000)
Prevent duplicate toasts (default: true). When enabled, showing the same toast plays a feedback animation instead of stacking.
Enable right-to-left layout at the code level (default: false). Only needed for JavaScript RTL - not required if using I18nManager.forceRTL().
Custom colors per toast type. Each type has accent (title/icon) and background colors.
Custom icons per toast type. Provide a render function that receives { color, size }.
Global ViewStyle overrides for all toast containers
Global TextStyle overrides for all toast titles
Global TextStyle overrides for all toast descriptions

​
Dismiss toasts programmatically

You can dismiss toasts manually using the returned ID or dismiss all toasts: 
import { toast } from 'react-native-bread';

// Get the toast ID when showing
const toastId = toast.success('Processing...', { duration: 60000 });

// Dismiss specific toast
toast.dismiss(toastId);

// Dismiss all toasts
toast.dismissAll();

​
Working with modals

Toasts automatically appear above modals on iOS. On Android, you have two options:

​
Option 1: Use contained modal (simplest)

On Android, containedModal looks identical to modal but keeps the React hierarchy: 
import { Platform } from 'react-native';

<Stack.Screen
  name="(modal)"
  options={{ 
    presentation: Platform.OS === 'android' ? 'containedModal' : 'modal' 
  }}
/>

​
Option 2: Use ToastPortal

For native modals, add ToastPortal inside your modal layouts:
app/(modal)/_layout.tsx
import { Stack } from 'expo-router';
import { ToastPortal } from 'react-native-bread';

export default function ModalLayout() {
  return (
    <>
      <Stack screenOptions={{ headerShown: false }} />
      <ToastPortal />
    </>
  );
}
ToastPortal only renders on Android - it returns null on iOS, so no platform check is needed.

​
Next steps

API reference

Explore the complete API documentation

Custom toasts

See real-world examples and advanced patterns

Customization

Learn how to customize colors, icons, and styles

Types

Type-safe toast usage with TypeScript

Build docs developers (and LLMs) love

Get started for freeTalk to us