Signature
toast.promise<T>(
promise: Promise<T>,
messages: PromiseMessages
): Promise<PromiseResult<T>>
Parameters
Configuration for loading, success, and error states
Promise messages
The messages object requires three properties:
Message to show while the promise is pending. Can be a string or an object with title, description, and duration.
Message to show when the promise resolves. Can be a string or an object with title, description, and duration.
error
ErrorMessageInput
required
Message to show when the promise rejects. Can be a string, an object with title, description, and duration, or a function that receives the error and returns a string or object.
loading: {
title: "Loading...",
description: "Fetching user data",
duration: 60000 // Optional: override duration for this state
}
error: (err) => ({
title: "Error",
description: err.message
})
Return value
Returns a Promise<PromiseResult<T>> with the following structure:
Success result
{
data: T,
success: true
}
Error result
{
error: Error,
success: false
}
Examples
Simple API call
const result = await toast.promise(
fetchUser(id),
{
loading: "Loading...",
success: "User loaded!",
error: "Failed to load user",
}
);
if (result.success) {
console.log(result.data);
} else {
console.error(result.error);
}
With detailed messages
toast.promise(
saveSettings(settings),
{
loading: {
title: "Saving...",
description: "Updating your settings",
},
success: {
title: "Saved!",
description: "Your settings have been updated",
},
error: {
title: "Save failed",
description: "Please try again",
},
}
);
With error message function
toast.promise(
uploadFile(file),
{
loading: {
title: "Uploading...",
description: file.name,
},
success: {
title: "Upload complete",
description: "File uploaded successfully",
},
error: (err) => ({
title: "Upload failed",
description: err.message,
}),
}
);
With custom durations
toast.promise(
longRunningTask(),
{
loading: {
title: "Processing...",
description: "This may take a while",
duration: 120000, // 2 minutes for loading
},
success: {
title: "Complete!",
description: "Task finished successfully",
duration: 6000, // 6 seconds for success
},
error: (err) => ({
title: "Task failed",
description: err.message,
duration: 8000, // 8 seconds for error
}),
}
);
Handling the result
const result = await toast.promise(
api.deleteAccount(),
{
loading: "Deleting account...",
success: "Account deleted",
error: "Failed to delete account",
}
);
if (result.success) {
// Navigate to login screen
navigation.navigate('Login');
} else {
// Log error for debugging
console.error('Delete failed:', result.error);
}
Multiple promise states
// Start multiple operations
const [user, settings, preferences] = await Promise.all([
toast.promise(fetchUser(id), {
loading: "Loading user...",
success: "User loaded",
error: "User failed",
}),
toast.promise(fetchSettings(id), {
loading: "Loading settings...",
success: "Settings loaded",
error: "Settings failed",
}),
toast.promise(fetchPreferences(id), {
loading: "Loading preferences...",
success: "Preferences loaded",
error: "Preferences failed",
}),
]);
if (user.success && settings.success && preferences.success) {
// All loaded successfully
initializeApp(user.data, settings.data, preferences.data);
}
Notes
- The loading toast has a default duration of 60 minutes (60 * 60 * 1000 ms) to prevent auto-dismiss during long operations
- Success and error toasts have a default duration of 4000ms (4 seconds)
- The toast automatically transitions from loading to success/error when the promise settles
- If the promise throws a non-Error value, it will be converted to an Error with
new Error(String(err))