Toast
Toasts are used to display brief messages or notifications that appear temporarily on the screen.
A Toast is a small, temporary notification that appears on the screen to inform users about the outcome of an action or to provide brief feedback. Toasts are commonly used in applications to deliver messages such as success notifications, error alerts, or informational updates without interrupting the user's workflow.
Anatomy
Appearance
The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.
| Property | Type | Description |
|---|---|---|
variant | default | success | warning | info | error | The available variants of this component. |
size | - | The available sizes of this component. |
Each variant uses a distinct icon color to signal the nature of the notification.
| Variant | Description | When to use |
|---|---|---|
default | Neutral toast with no specific semantic color. This is the default variant. | General notifications that don't fall into a specific status category. |
success | Toast with a green success icon. | Confirming a completed action, like saving data or sending a message. |
warning | Toast with a yellow warning icon. | Alerting users to potential issues that don't block their workflow. |
info | Toast with a blue info icon. | Providing contextual information or updates, like sync status or tips. |
error | Toast with a red error icon. | Notifying users of failed actions or critical errors that need attention. |
Usage
The <ToastProvider> Component should be in the root of your application, so it can be used anywhere in your app. You can use the addToast function to add a Toast to the Toaster. The Toast will appear at the bottom right of the screen by default. With the position prop you can change the position of all Toasts.
Simple toast
A Toast should be used when you want to give users quick, non-intrusive feedback after an action, such as saving, deleting, or uploading data. It appears on the edge of the screen and should remain visible for at least 5 seconds or until the user manually dismisses it. Because it doesn't interrupt the user's workflow, a Toast is ideal for success messages, notifications, or error alerts that don't need immediate interaction. The message should be clear, concise, and easy to read.
import { Button, ToastProvider, useToast } from '@marigold/components';export default () => { const { addToast } = useToast(); return ( <> <ToastProvider position="bottom-right" /> <Button onPress={() => addToast({ title: 'Simple Toast', variant: 'success' })} > Show Toast </Button> </> );};Auto dismiss
This Toast will automatically dismiss itself after a specified duration. This is useful for notifications that do not require user interaction and should disappear after a short time. The time is in milliseconds.
import { Button, useToast } from '@marigold/components';export default () => { const { addToast } = useToast(); return ( <> <Button onPress={() => addToast({ title: 'Updated', description: 'I will vanish after 5 seconds', variant: 'info', timeout: 5000, }) } > Show Toast </Button> </> );};Programmatic dismiss
addToast does return the key of the Toast, with this the Toast can be dismissed programmatically, by saving the key of the Toast and then using removeToast.
import { useState } from 'react';import { Button, useToast } from '@marigold/components';export default () => { const [toastKey, setToastKey] = useState<string | null>(null); const { addToast, removeToast } = useToast(); return ( <> <Button onPress={() => { if (!toastKey) { setToastKey( addToast({ title: 'Error', description: 'Click the Hide Toast button to dismiss me!', variant: 'error', }) ); } else { removeToast(toastKey); setToastKey(null); } }} > {toastKey ? 'Hide' : 'Show'} Toast </Button> </> );};Close all toasts
All Toasts can be dismissed with clearToasts.
import { Button, useToast } from '@marigold/components';export default () => { const { addToast, clearToasts } = useToast(); return ( <div className="flex flex-row gap-2"> <Button onPress={() => addToast({ title: 'Updated Settings', variant: 'success', }) } > Show Toast </Button> <Button onPress={clearToasts}>Clear Toasts</Button> </div> );};Action
Toasts can also include an action element, which is typically a button or link that allows the user to take a specific action related to the toast message. This is useful for scenarios where you want to provide users with a way to respond to the notification.
To add an action element, use the action prop which accepts any React component (button, link, etc.).
import { Button, Link, useToast } from '@marigold/components';export default () => { const { addToast } = useToast(); return ( <div className="flex flex-row gap-2"> <Button onPress={() => addToast({ title: 'Update Available', variant: 'info', description: 'A new version is available.', timeout: 0, action: ( <Link size="small" href="https://github.com/marigold-ui/marigold"> Update now </Link> ), }) } > Show Toast with Link </Button> <Button onPress={() => addToast({ title: 'File Upload Failed', variant: 'error', description: 'The file could not be uploaded due to network issues.', timeout: 0, action: ( <Button size="small" variant="primary"> Retry </Button> ), }) } > Show Toast with Button </Button> </div> );};Props
Toast Provider
Prop
Type