API.md

API

showToast(options)

Displays a native toast notification.

import { showToast } from '@synonymdev/react-native-toast';

showToast({
	type: 'success',
	title: 'Saved',
	description: 'Your changes are ready.',
});

Toast Options

type ToastOptions = {
	type: 'success' | 'info' | 'warning' | 'error';
	title: string;
	description?: string;
	autoHide?: boolean;
	dismissible?: boolean;
	haptics?: boolean;
	durationMs?: number;
	style?: NativeToastStyle;
};

Option	Default	Description
type	Required	Visual variant for the toast.
title	Required	Primary toast text.
description	undefined	Secondary toast text.
autoHide	true	Whether the toast dismisses itself after durationMs.
dismissible	true	Whether the toast can be dismissed with an upward swipe.
haptics	false	Whether to trigger native haptic feedback when the toast is shown.
durationMs	4000	Auto-hide delay in milliseconds. Native implementations enforce a minimum visible duration.
style	undefined	Native style overrides.

Set autoHide: false to keep a toast visible until another toast replaces it or the user dismisses it.

Global Configuration

Use configureToast once during app startup to customize the base style or built-in variant styles for every toast.

import { configureToast, resetToastConfig } from '@synonymdev/react-native-toast';

configureToast({
	options: {
		haptics: true,
		dismissible: true,
		durationMs: 4000,
	},
	defaults: {
		borderRadius: 16,
		paddingHorizontal: 24,
	},
	variants: {
		success: {
			backgroundColor: '#047857',
			borderColor: '#34D399',
		},
		error: {
			backgroundColor: '#991B1B',
			borderColor: '#FCA5A5',
		},
	},
});

resetToastConfig();

type NativeToastVariantStyles = Partial<
	Record<NativeToastVariant, NativeToastStyle>
>;

type NativeToastDefaultOptions = Pick<
	ToastOptions,
	'autoHide' | 'dismissible' | 'haptics' | 'durationMs'
>;

type NativeToastConfig = {
	defaults?: NativeToastStyle;
	variants?: NativeToastVariantStyles;
	options?: NativeToastDefaultOptions;
};

Configured behavior options are merged in this order:

1. Configured options.
2. Per-toast options.

Per-toast options always win.

Configured styles are merged in this order:

1. Built-in default style.
2. Configured defaults.
3. Built-in variant style.
4. Configured variant style.
5. Per-toast style.

Styling

Pass style to override the native toast appearance.

showToast({
	type: 'info',
	title: 'New message',
	description: 'You have a new notification.',
	style: {
		backgroundColor: '#111111',
		iosBlurEffect: 'systemThinMaterialDark',
		iosBlurAmount: 20,
		iosBlurTintOpacity: 0.72,
		borderColor: '#333333',
		borderRadius: 12,
		borderWidth: 1,
		paddingHorizontal: 20,
		paddingVertical: 16,
		width: 320,
		maxWidth: 420,
		titleColor: '#FFFFFF',
		titleFontSize: 15,
		descriptionColor: '#D4D4D4',
		descriptionFontSize: 13,
		shadowColor: '#000000',
		shadowOpacity: 0.35,
		shadowRadius: 16,
		shadowOffsetY: 8,
		shadowElevation: 8,
		animation: 'slide-fade',
		animationDurationMs: 200,
	},
});

Style Options

type NativeToastBlurEffect =
	| 'none'
	| 'extraLight'
	| 'light'
	| 'dark'
	| 'regular'
	| 'prominent'
	| 'systemUltraThinMaterial'
	| 'systemThinMaterial'
	| 'systemMaterial'
	| 'systemThickMaterial'
	| 'systemChromeMaterial'
	| 'systemUltraThinMaterialLight'
	| 'systemThinMaterialLight'
	| 'systemMaterialLight'
	| 'systemThickMaterialLight'
	| 'systemChromeMaterialLight'
	| 'systemUltraThinMaterialDark'
	| 'systemThinMaterialDark'
	| 'systemMaterialDark'
	| 'systemThickMaterialDark'
	| 'systemChromeMaterialDark';

type NativeToastStyle = {
	backgroundColor?: string;
	iosBlurEffect?: NativeToastBlurEffect;
	iosBlurAmount?: number;
	iosBlurTintOpacity?: number;
	borderRadius?: number;
	borderColor?: string;
	borderWidth?: number;
	shadowColor?: string;
	shadowOpacity?: number;
	shadowRadius?: number;
	shadowOffsetX?: number;
	shadowOffsetY?: number;
	shadowElevation?: number;
	animation?: 'none' | 'fade' | 'slide' | 'slide-fade';
	animationDurationMs?: number;
	width?: number;
	maxWidth?: number;
	marginHorizontal?: number;
	padding?: number;
	paddingHorizontal?: number;
	paddingVertical?: number;
	paddingTop?: number;
	paddingRight?: number;
	paddingBottom?: number;
	paddingLeft?: number;
	titleColor?: string;
	titleFontFamily?: string;
	titleFontSize?: number;
	titleFontWeight?: 'normal' | 'medium' | 'semibold' | 'bold';
	descriptionColor?: string;
	descriptionFontFamily?: string;
	descriptionFontSize?: number;
	descriptionFontWeight?: 'normal' | 'medium' | 'semibold' | 'bold';
};

iosBlurEffect uses native UIBlurEffect on iOS and is ignored by Android. iosBlurAmount controls the custom blur radius and defaults to 20. iosBlurTintOpacity controls the opacity of the backgroundColor tint layered over the blur and defaults to 0.72.

Supported animations are none, fade, slide, and slide-fade.