GitHub icon

Usage

Toast notifications are used when:

The user does not need to be interrupted.
The user is being informed of an event, with the option to take action.
The results of an action are delayed.
The notification could appear anywhere in the application.

All notifications share the non-interruptive function. Banner notifications are tied to a specific view and are usually generated immediately after a save. Announcement notifications convey an app-wide event and not feedback on a workflow. Snackbar notifications are less-intrusive, concise messages that inform a user that an action has been completed.

Status Variations

Info (Default)

Communicates operational information to the user. These are commonly used to denote the start of an operation, and usually includes follow up notifications. A one-off acknowledgement notification could also be a Snackbar. If content in an area needs to be blocked with an operation, a loading mask could be used over the Info Toast.

Success

Communicates the success of an operation, e.g. a long-running process has finished. These are often paired with an info toast.

Critical/Error

Toast errors are when an operation was unable to be performed or has failed. Page-specific and form errors should utilize the Banner notification. When applicable, users should be able to take action on an operation.

Warning

Warnings are distinct from errors and represent issues that do not need an immediate resolution, but still need to be addressed. Unintended consequences in an operation and fallback choices are common examples. Users in general should be able to take action on a warning.

Actions

0–2 actions can be added to each Toast. Action styling is predefined as one primary and one secondary action.

Close Action

In general, toast should be dismissible. Important, persistent events are the general exception.

With a Progress Bar

When it is possible to calculate the time it takes to complete a task, a Toast can be paired with a Progress Bar.

<Toast.Group portal={false}>
	<Toast
		status="info"
		title="Import Adjustments"
		portal={false}
		duration={0}
	>
		In progress
		<ProgressBar progress={30} small blue className="m-t-1" />
	</Toast>
	<Toast
		status="success"
		title="Successful Import"
		onPrimaryActionClick={() => {}}
		primaryActionName="View Import"
		portal={false}
		duration={0}
	>
		<ProgressBar progress={100} small green className="m-t-3" />
	</Toast>
	<Toast
		status="critical"
		title="Error in Import Adjustment"
		onPrimaryActionClick={() => {}}
		primaryActionName="Widget Page"
		portal={false}
		duration={0}
	>
		There was an error in processing the import.
		<ProgressBar progress={60} small red className="m-t-1" />
	</Toast>
</Toast.Group>

Duration

By default, Toasts expire after 8 seconds which is our recommended expiration duration. This can also be set to only expire on user action by removing the duration.

Grouped Toasts

Multiple Toasts can be displayed on the screen. In general, newer toasts should appear at the top of the group. By default, only 5 toasts are shown at a time. Older messages are hidden from view for newer messages.

<State initial={{ index: 0, items: [] }}>
	{([state, setState]) => (
		<>
			<Toast.Group>
				{state.items.map(index => (
					<Toast
						key={index}
						portal={false}
						title={`Message #${index}`}
						onClose={() => setState({
							items: state.items.filter(idx => idx !== index)
						})}
						onPrimaryActionClick={() => setState({
							items: state.items.filter(idx => idx !== index)
						})}
						primaryActionName="Close"
					/>
				))}
			</Toast.Group>
			<Button onClick={() => setState({
				index: state.index + 1,
				items: [state.index].concat(state.items)
			})}>Demo Multiple Toasts</Button>
		</>
	)}
</State>

Best Practices

Titles should not stretch beyond two lines.
In a queue, priority is given to critical/error statuses, followed by order in which they are generated.
Don't use an action button to close the toast.
Don't use this pattern for handling page specific errors.
Avoid blaming the user for an operational error. Accept blame when we know it's our fault.
Avoid excessive use of the pattern. While these do not interrupt the user, they can be distracting.
Avoid technical jargon.

To require a user interaction, use a Modal component.
For critical information that requires a specific decision, use a Dialog component.

For non-intrusive notifications:

Site-wide information about an event, use the Announcement notification.
Content specific to the page, use the Banner notification.
Quick, successful information, use the Snackbar notification.

Importing

import { Toast } from '@servicetitan/design-system';

Toast