Skip to main content
By default, toasts automatically appear above native modals on iOS. On Android, native modals render outside the React hierarchy, requiring additional setup to show toasts above them.

​
How it works on iOS

On iOS, <BreadLoaf /> uses FullWindowOverlay from react-native-screens to render toasts in a native window above all other content, including modals. No additional setup is needed. 
// iOS: Works automatically
import { BreadLoaf } from 'react-native-bread';
import { Stack } from 'expo-router';

export default function RootLayout() {
  return (
    <>
      <Stack>
        <Stack.Screen name="index" />
        <Stack.Screen name="modal" options={{ presentation: 'modal' }} />
      </Stack>
      <BreadLoaf />
    </>
  );
}

​
Android solutions

On Android, you have two approaches:

Use containedModal

Simplest solution. Renders modals within the React hierarchy.

Use ToastPortal

For native modals. Add a portal component inside modal layouts.
The easiest solution is to use containedModal presentation on Android. This renders the modal within the React hierarchy, so toasts from your root <BreadLoaf /> remain visible. 
import { Platform } from 'react-native';
import { Stack } from 'expo-router';
import { BreadLoaf } from 'react-native-bread';

export default function RootLayout() {
  return (
    <>
      <Stack>
        <Stack.Screen name="index" />
        <Stack.Screen 
          name="modal" 
          options={{ 
            presentation: Platform.OS === 'android' ? 'containedModal' : 'modal'
          }} 
        />
      </Stack>
      <BreadLoaf />
    </>
  );
}
On Android, modal and containedModal look nearly identical to the user. The main difference is whether the modal renders in a native window (modal) or within the React tree (containedModal).

​
When to use containedModal

  • Most app modals and sheets
  • Settings screens
  • Form modals
  • Detail views
  • Edit screens

​
Option 2: Use ToastPortal

If you need true native modals on Android, add <ToastPortal /> inside your modal layouts:
1

Create a modal layout file

Add a _layout.tsx file in your modal route group:
// 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 />
    </>
  );
}
2

Configure modal presentation

Set the modal group to use native modal presentation:
// app/_layout.tsx
import { Stack } from 'expo-router';
import { BreadLoaf } from 'react-native-bread';

export default function RootLayout() {
  return (
    <>
      <Stack>
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
        <Stack.Screen 
          name="(modal)" 
          options={{ presentation: 'modal' }} 
        />
      </Stack>
      <BreadLoaf />
    </>
  );
}
3

Show toasts from modal screens

Toasts triggered from modal screens will now appear correctly:
// app/(modal)/settings.tsx
import { toast } from 'react-native-bread';
import { View, Button } from 'react-native';

export default function SettingsScreen() {
  return (
    <View>
      <Button
        title="Save Settings"
        onPress={() => {
          // This toast will appear above the modal on Android
          toast.success('Settings saved!');
        }}
      />
    </View>
  );
}
ToastPortal automatically returns null on iOS (where it’s not needed), so you don’t need platform-specific code.

​
Understanding ToastPortal

The ToastPortal component is a lightweight renderer that shares the same toast queue as your root <BreadLoaf /> component.

​
Key characteristics

  • Android only: Automatically returns null on iOS
  • No configuration: Inherits all styling and behavior from root <BreadLoaf />
  • Shared queue: Shows the same toasts as the main component
  • Lightweight: Only renders the toast container, not the full provider
// ToastPortal implementation (simplified)
export function ToastPortal() {
  if (Platform.OS !== 'android') {
    return null;
  }
  return <ToastContent />;
}

​
Complete Expo Router example

Here’s a full example with both tabs and modals:
app/_layout.tsx
import { Stack } from 'expo-router';
import { BreadLoaf } from 'react-native-bread';

export default function RootLayout() {
  return (
    <>
      <Stack>
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
        <Stack.Screen name="(modal)" options={{ presentation: 'modal' }} />
        <Stack.Screen name="+not-found" />
      </Stack>
      <BreadLoaf
        config={{
          position: 'top',
          defaultDuration: 4000,
        }}
      />
    </>
  );
}
app/(modal)/_layout.tsx
import { Stack } from 'expo-router';
import { ToastPortal } from 'react-native-bread';

export default function ModalLayout() {
  return (
    <>
      <Stack>
        <Stack.Screen 
          name="settings" 
          options={{ 
            title: 'Settings',
            headerShown: true,
          }} 
        />
        <Stack.Screen 
          name="profile" 
          options={{ 
            title: 'Edit Profile',
            headerShown: true,
          }} 
        />
      </Stack>
      <ToastPortal />
    </>
  );
}
app/(modal)/settings.tsx
import { View, Button, StyleSheet } from 'react-native';
import { toast } from 'react-native-bread';
import { router } from 'expo-router';

export default function SettingsScreen() {
  const handleSave = async () => {
    const result = await toast.promise(
      saveSettings(),
      {
        loading: 'Saving settings...',
        success: 'Settings saved!',
        error: 'Failed to save settings',
      }
    );

    if (result.success) {
      router.back();
    }
  };

  return (
    <View style={styles.container}>
      <Button title="Save" onPress={handleSave} />
      <Button title="Cancel" onPress={() => router.back()} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 16,
    gap: 12,
  },
});

​
React Navigation example

If you’re using React Navigation instead of Expo Router:
App.tsx
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { BreadLoaf } from 'react-native-bread';
import { Platform } from 'react-native';

const Stack = createNativeStackNavigator();

export default function App() {
  return (
    <>
      <NavigationContainer>
        <Stack.Navigator>
          <Stack.Screen name="Home" component={HomeScreen} />
          <Stack.Screen 
            name="Modal" 
            component={ModalScreen}
            options={{
              presentation: Platform.OS === 'android' ? 'containedModal' : 'modal'
            }}
          />
        </Stack.Navigator>
      </NavigationContainer>
      <BreadLoaf />
    </>
  );
}

​
With ToastPortal in nested navigators

ModalNavigator.tsx
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { ToastPortal } from 'react-native-bread';
import SettingsScreen from './SettingsScreen';
import ProfileScreen from './ProfileScreen';

const Stack = createNativeStackNavigator();

export function ModalNavigator() {
  return (
    <>
      <Stack.Navigator>
        <Stack.Screen name="Settings" component={SettingsScreen} />
        <Stack.Screen name="Profile" component={ProfileScreen} />
      </Stack.Navigator>
      <ToastPortal />
    </>
  );
}
App.tsx
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { BreadLoaf } from 'react-native-bread';
import { ModalNavigator } from './ModalNavigator';

const Stack = createNativeStackNavigator();

export default function App() {
  return (
    <>
      <NavigationContainer>
        <Stack.Navigator>
          <Stack.Screen name="Home" component={HomeScreen} />
          <Stack.Screen 
            name="Modal" 
            component={ModalNavigator}
            options={{ presentation: 'modal' }}
          />
        </Stack.Navigator>
      </NavigationContainer>
      <BreadLoaf />
    </>
  );
}

​
Troubleshooting

Make sure you’ve either:
  1. Changed presentation to 'containedModal' on Android, OR
  2. Added <ToastPortal /> inside your modal layout
Check that the modal is actually rendering as a native modal (check the screen options).
You may have both <BreadLoaf /> and <ToastPortal /> configured for a containedModal. Use ToastPortal only for native modals (presentation: 'modal').
// ❌ Don't do this
<Stack.Screen 
  name="modal" 
  options={{ presentation: 'containedModal' }} 
/>
// ... with ToastPortal in the modal layout

// ✅ Do this instead
<Stack.Screen 
  name="modal" 
  options={{ presentation: 'containedModal' }} 
/>
// ... no ToastPortal needed
ToastPortal inherits configuration from your root <BreadLoaf />. Make sure you’re not creating multiple BreadLoaf instances with different configs.All configuration should be done in one place:
// ✅ Configure once in root layout
<BreadLoaf config={{ position: 'bottom', ... }} />

// ✅ ToastPortal in modal (no config)
<ToastPortal />
This is expected behavior if you’re using native modals without ToastPortal. Add ToastPortal to your modal layouts or switch to containedModal presentation.

​
API reference

​
ToastPortal

function ToastPortal(): JSX.Element | null
A lightweight toast renderer for Android modals. Returns null on iOS. Usage: Place inside modal layout components where you need toasts to appear above native Android modals. Inherits: All configuration from root <BreadLoaf /> component. Platform: Android only (returns null on iOS). 
import { ToastPortal } from 'react-native-bread';

// Inside modal layout
export default function ModalLayout() {
  return (
    <>
      <Stack />
      <ToastPortal />
    </>
  );
}

Build docs developers (and LLMs) love

Get started for freeTalk to us