lab components / Feedback

Toast

A toast is a passive, non-modal notification that informs the user of changes or updates as a result of an action.

Basic usage Clear toasts Examples Examples with links Examples with external html Toast dropzone Properties Guidelines

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

#Basic usage

A Toast is displayed at the top of the page and remains there until it is dismissed by the user.

There are four types of Toast: success, info, warning, and error. Using different types of Toast helps users understand what type of information is being communicated and how they should respond.

Success

Let the user know their action was completed as expected. If the user just created something, allow them to view it. For example, “Policy template updated.” or “Email template updated.” Follow the writing guideline for Progress and congratulations.

Information

Provide the user with neutral and additional information. Make sure Toast has a clear purpose and supports (not impedes) the user. Be brief and provide only the information relevant to the task. For example, “The initial crawlers may take a few days to complete. Read scan process”. Follow the writing guideline for Help content for complex workflows.

Warning

Make the user aware of a condition or potential problem with a warning message. For example, “Renew your subscription” Avoid writing something that has already occurred. Instead, use an error toast. Follow the writing guideline for Errors and warnings.

Error

Inform the user of an error or failure and possibly prevent the user from continuing until the problem is resolved. Point out the exact location of the problem - where the user should go and what steps are required to resolve the problem. For example, “Cannot add the file. The file already existed. Please upload again.” Follow the writing guideline for Issues and issue descriptions.

CodeHTML output

const showToast = useShowToast();
return (
	<>
		<button
			aria-haspopup="dialog"
			onClick={() => showToast({ message: "Success", type: "success" })}
		>
			Success
		</button>
		<button aria-haspopup="dialog" onClick={() => showToast({ message: "Info", type: "info" })}>
			Info
		</button>
		<button
			aria-haspopup="dialog"
			onClick={() => showToast({ message: "Warning", type: "warning" })}
		>
			Warning
		</button>
		<button aria-haspopup="dialog" onClick={() => showToast({ message: "Error", type: "error" })}>
			Error
		</button>
	</>
);

#Clear toasts

useClearToast is not a feature for end users. The user can clear the Toast by clicking the close button, or pressing escape. The Toast can also be cleared programmatically if you i.e. have a single-page application, where you want to clear the Toast on page navigation. To clear the Toast from anywhere use the useClearToast hook from anywhere in your code. Could be your routing framework, or in this case, an arbitrary button.

CodeHTML output

const clearToast = useClearToast();
return <button onClick={clearToast}>Clear toasts programatically</button>;

#Examples

To provide users with a consistent experience, the Toast type has a corresponding color and icon. By default, Toast contains an icon, inline text, an optional link, and a close button.

Icon: the colour and icon give the user a visual indication of the message at a glance.
Inline text: provide short and clear text that directly relates to the task at hand. See the writing guideline below.
Link: an optional link that takes the user to a page with more details or an action that the user can perform.
Close button: closes the toast.

CodeHTML output

<Toast type="success" message="Some success message" />
<Toast type="info" message="Some neutral message" />
<Toast type="warning" message="Some warning message" />
<Toast type="error" message="Some error message" />

#Examples with links

A Toast with a link allows the user to interact with the content and perform an action through a shortcut. This link should be short and navigate the user to a page or modal where the user can take action to resolve the issue or find more information. See Link guideline. Use a Toast with a link as follows:

Use only one link per toast.
Be clear about what action the user can take.
A link should only be a shortcut for the user.
Make sure that the user can reach the link in the message in other ways.

Support Undo

Remember that the user often takes an action by mistake. Allow the user to correct mistakes by displaying an “Undo” action. This promotes a sense of freedom and confidence for the user.

CodeHTML output

<Toast
	type="success"
	message={
		<>
			Some success message with a <a href="#examples-with-links">link</a>
		</>
	}
/>

#Examples with external html

If the user will open a new tab or window with the link, use the style to match the user behavior. Follow Example with links.

CodeHTML output

<Toast
	type="success"
	message={
		<ExternalHtml>
			{"Some success message with a <a href='#examples-with-external-html'>link</a>"}
		</ExternalHtml>
	}
/>

#Toast dropzone

ToastDropzone is not a feature for end users. It is a structural component that allows developers to control where the Toast component will appear in the Document Object Model (DOM).

By default toasts are appended to the DOM in the bottom of <body>. ToastDropzone lets you to control where in the DOM the Toasts are rendered, allowing it to inherit styles, if you don't use a global stylesheet.

CodeHTML output

<ToastDropzone />

#Properties

CodePropsHTML output

Property	Description	Defined
typeRequired	`"error" \| "info" \| "success" \| "warning"`	YesNo
messageOptional	`element`	YesNo
onCloseOptional	`function`	YesNo
aria-labelOptional	`string`	YesNo
childrenOptional	`element`	YesNo

#Guidelines

#Best practices

#General

Use the Toast when it is relevant to the user's goal and is presented in the context of what they are doing.

#Usage

The Toast is typically used for the following purpose:

Feedback on the user’s intent

The main use case for the Toast is to notify users of actions or tasks they have initiated. For example, you might use a success toast to notify a user that they have successfully deleted something because their intended action was successful. You could send a Toast if users

Add a new feature
Change a setting
Delete a site
Edit a user permission

An example of a Toast can be found in Main menu > Policy > My Policies > Edit policy

#Style

The content format is set to plain text. It is not recommended to use any additional content format such as buttons, headings, paragraphs or lists.
A Toast should contain only a single line of inline text. In wide layouts, you should increase the width of the container to accommodate longer inline text. In a narrow layout, you should try to explain the text in three words. As mentioned in the writing guidelines below, you should limit words in toasts.

#Dismissal

If a new Toast appears, the former Toast will automatically disappear.
By default, the Toast can only disappear if it is manually dismissed. This way, the Toast remains accessible to the user who needs more time to read the text or wants to refer back to the text.
Note that after the Toast disappears, the user can no longer access the message.
When a Modal is opened, a Toast should always be dismissed.

#Do not use when

containing high-priority information that requires their attention or action. Use Modal instead.
containing system or product level or medium-priority information. In this case, use Message instead.
the information is not task-specific.
the user interacts with a form or modal to perform an action. In this case, use Form Element Wrapper to display a validation error or warning message.

#Accessibility

#For designers

When including a link in the Toast, make sure it can stand on its own, and avoid generic text such as "Click here" or "Read more".
Avoid frequent interruptions with the Toast, especially for users with visual and cognitive disabilities.
Avoid displaying the Toast when the page loads.
When the Toast is manually closed, designers should decide where the keyboard focus should go and communicate this to developers. Ideally, the element with focus state should make it easier for users to reach their goals.
- Scenario 1: whenever the user open a modal or a dialog box, the user should move the focus there. When the user close it again, the focus should be moved back to the button that opened it.
- Scenario 2: if clicking a “Delete This Item” button also removes the button itself, you should consider where it makes sense to place the focus. Read the guideline for managing focus.

#For developers

Make sure that the keyboard focus moves to a meaningful place when the toast is closed manually. Note that this decision should be discussed with designers.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

Limit the text to one line for all types of Toast.
Be clear, concise, and easy to understand.
Use the {noun} + {verb} form. For example, write "Tags updated" rather than "Your tags have been updated". The extra words are not necessary because the user already understands the context.
Remember that the text may become longer when translated.
Avoid technical jargon.
Use sentence case for inline text and end a sentence with a period.
Avoid unnecessary words and articles such as "the," "an" or "a".
Use the Siteimprove voice. Be capable, personable, insightful, and clear and not system-centric. Follow the Tone Of the Voice.