Overview
BreadLoaf is the main toast provider component for React Native Bread. Add it to your root layout to enable toast notifications throughout your app.
On iOS, toasts render using FullWindowOverlay to appear above native modals. On Android, use ToastPortal inside modal screens for toast support.
Basic usage
import { BreadLoaf } from 'react-native-bread';
export default function RootLayout() {
return (
<>
<Stack />
<BreadLoaf />
</>
);
}
Configuration
import { BreadLoaf } from 'react-native-bread';
export default function RootLayout() {
return (
<>
<Stack />
<BreadLoaf
config={{
position: 'bottom',
stacking: false,
defaultDuration: 5000,
colors: {
success: { accent: '#22c55e', background: '#f0fdf4' },
error: { accent: '#ef4444', background: '#fef2f2' },
},
toastStyle: { borderRadius: 12 },
}}
/>
</>
);
}
Props
Configuration object for customizing toast behavior and appearance. All properties are optional.
Show properties
Show properties
Where toasts appear on screen.
Extra spacing from screen edge in pixels, added on top of safe area insets.
Enable right-to-left layout at the code level (reverses icon/text order and text alignment). Only needed when you handle RTL in JavaScript — native RTL (e.g. via
I18nManager.forceRTL) already flips the entire layout automatically, so this option is unnecessary in that case.Show multiple toasts stacked. When
false, only one toast shows at a time.Maximum number of visible toasts when stacking is enabled.
Whether toasts can be swiped to dismiss.
Show close button on toasts. Loading toasts never show close button.
Default display time in milliseconds for toasts.
Deduplicate repeated toasts, resetting timer with pulse/shake animation. Matches by title, type, and description, or by
id if provided.Customize colors per toast type (
success, error, info, loading).Each toast type accepts:accent(string): Color for title text and iconsbackground(string): Background color of the toast
<BreadLoaf
config={{
colors: {
success: { accent: '#22c55e', background: '#f0fdf4' },
error: { accent: '#ef4444', background: '#fef2f2' },
info: { accent: '#3b82f6', background: '#eff6ff' },
loading: { accent: '#6b7280', background: '#f9fafb' },
},
}}
/>
Custom icons per toast type. Provide a render function that receives
color and size props.import { CloseIcon } from 'react-native-bread';
<BreadLoaf
config={{
icons: {
error: ({ color, size }) => (
<CloseIcon color={color} size={size} />
),
},
}}
/>
Style overrides for the toast container. Supports standard React Native view styles like
borderRadius, padding, shadow properties, etc.<BreadLoaf
config={{
toastStyle: {
borderRadius: 12,
paddingHorizontal: 16,
paddingVertical: 12,
},
}}
/>
Style overrides for the title text. Supports standard React Native text styles.
<BreadLoaf
config={{
titleStyle: {
fontSize: 16,
fontWeight: '600',
},
}}
/>
Style overrides for the description text. Supports standard React Native text styles.
<BreadLoaf
config={{
descriptionStyle: {
fontSize: 14,
opacity: 0.8,
},
}}
/>
Advanced example
import { BreadLoaf, CloseIcon, GreenCheck } from 'react-native-bread';
export default function RootLayout() {
return (
<>
<Stack />
<BreadLoaf
config={{
position: 'top',
offset: 20,
stacking: true,
maxStack: 5,
dismissible: true,
showCloseButton: true,
defaultDuration: 5000,
deduplication: true,
colors: {
success: {
accent: '#10b981',
background: '#d1fae5',
},
error: {
accent: '#ef4444',
background: '#fee2e2',
},
info: {
accent: '#3b82f6',
background: '#dbeafe',
},
loading: {
accent: '#6b7280',
background: '#f3f4f6',
},
},
icons: {
success: ({ color, size }) => (
<GreenCheck color={color} size={size} />
),
error: ({ color, size }) => (
<CloseIcon color={color} size={size} />
),
},
toastStyle: {
borderRadius: 16,
paddingHorizontal: 20,
paddingVertical: 14,
shadowColor: '#000',
shadowOffset: { width: 0, height: 2 },
shadowOpacity: 0.1,
shadowRadius: 8,
elevation: 4,
},
titleStyle: {
fontSize: 16,
fontWeight: '700',
letterSpacing: 0.2,
},
descriptionStyle: {
fontSize: 14,
lineHeight: 20,
marginTop: 4,
},
}}
/>
</>
);
}
Type definitions
type ToastType = 'success' | 'error' | 'info' | 'loading';
type ToastPosition = 'top' | 'bottom';
interface ToastTypeColors {
/** Accent color used for title text and icons */
accent: string;
/** Background color of the toast */
background: string;
}
interface IconProps {
/** The accent color from the theme for this toast type */
color: string;
/** Default icon size */
size: number;
}
type IconRenderFn = (props: IconProps) => ReactNode;
type ToastConfig = {
position?: 'top' | 'bottom';
offset?: number;
rtl?: boolean;
stacking?: boolean;
maxStack?: number;
dismissible?: boolean;
showCloseButton?: boolean;
defaultDuration?: number;
deduplication?: boolean;
colors?: Partial<Record<ToastType, Partial<ToastTypeColors>>>;
icons?: Partial<Record<ToastType, IconRenderFn>>;
toastStyle?: ViewStyle;
titleStyle?: TextStyle;
descriptionStyle?: TextStyle;
};