Toast

View source on GitHub
; Opens a new tab
See recent changes on GitHub
; Opens a new tab

Toasts are brief and small messages that overlay content, but do not block the user’s flow, as they are out of the way and ephemeral.

Toasts do not require user action and primarily acknowledge that a user has performed an action or completed a task.

also known as Snackbar

Figma:
Ready
Web:
Ready
iOS:
N/A
Android:
N/A
A11y:
Partially ready

Props

Component props
Name
Type
Default
text
Required
string | React.Element<typeof Text>
-

Main content of Toast. Content should be localized. See the Text variant to learn more.

dismissButton
{|
  accessibilityLabel?: string,
  onDismiss: () => void,
|}
-

Adds a dismiss button to Toast. See the Dismissible variant for more info.
The accessibilityLabel should follow the Accessibility guidelines.

{|
  text: string,
  accessibilityLabel: string,
  href: string,
  onClick?: ({|
    event: SyntheticMouseEvent<HTMLAnchorElement> | SyntheticKeyboardEvent<HTMLAnchorElement>,
    dangerouslyDisableOnNavigation: () => void,
  |}) => void,
|}
-

Helper Link to be placed after the subtext. See the helper link variant to learn more.

primaryAction
{|
  accessibilityLabel: string,
  href?: string,
  label: string,
  onClick?: $ElementType<ElementConfig<typeof Button>, "onClick">,
  rel?: $ElementType<ElementConfig<typeof Link>, "rel">,
  size?: $ElementType<ElementConfig<typeof Button>, "size">,
  target?: $ElementType<ElementConfig<typeof Link>, "target">,
|}
-

Adds an optional button for user interaction. Generally not recommended given the ephemeral nature of Toasts.

thumbnail
{| image: React.Element<typeof Image> |}
| {| avatar: React.Element<typeof Avatar> |}
| {| icon: React.Element<typeof Icon> |}
-

An optional thumbnail to display next to the text.

type
"default" | "success" | "error" | "progress"
"default"

See the type variant to learn more.

Usage guidelines

When to use
  • Briefly acknowledging a user action without interrupting their flow.
  • When acknowledging an action that relates to another surface, providing a link that navigates the user to that surface.
  • To undo actions after acknowledgement, if there isn’t already a way to do so on the current surface.
  • For system processes like showing that a process is loading, or when there are internet connectivity issues.
When not to use
  • When, due to an error, a user can’t even continue performing basic tasks like browsing already loaded Pins.
  • When asking a user to confirm that they want to perform an action. Use ModalAlert instead.
  • When you want to suggest a user spend more money or try new features; use Upsell instead.
  • For errors that relate to a specific section or page. Use Callout(/web/callout) or SlimBanner(/web/slimbanner) instead.
  • To guide or educate the user. Use Popover(/web/popover) or Tooltip(/web/tooltip) instead.

Accessibility

Icons

iconAccessibilityLabel requires a short, descriptive label for screen readers. This label should communicate the intent of the icon, such as "Success", “Error”, “Link”. It should also be localized.

Duration

Some people may take longer to read toasts than others due to cognitive impairments. Use the guide below to set duration for Toasts:

  • Brief text of approximately 10–15 words (including button text): 5s
  • Longer than 15 words: Slow readers can read about 125–200 words per minute. Base your duration on the slowest number. For example, a toast with 20 words should be set to 10s. Learn more.

Localization

Remember to localize text and any string within primaryAction, helperLink or dismissButton.

Best practices

Do

Place Toasts out of the way so that a user can still navigate and complete tasks. Keep a bottom margin that is the same size as the left and right margins.

Don't

Block navigation controls with Toasts or align too close to the edge of a navigation bar.

Do

Show one Toast at a time, with errors and acknowledgements taking priority.

Don't

Stack multiple toasts as that will block the user.

Do

Use concise text to avoid blocking the user with a large toast.

Don't

Be wordy so that toasts increase in size, block content and disappear before a user can finish reading them. Truncate text after two lines, unless it will make it hard to understand the desired message.

Do

Include a way to dismiss the toast when it is actionable or contains multiple lines of text. On desktop, toasts can be dismissed via an icon button; on mobile web via swiping on the toast in any direction.

Don't

Leaving toasts on screen for a long time without a way to dismiss. Exceptions are blocking error toasts that need to persist across surfaces until a user takes action.

Do

Make interaction optional and secondary. Toasts are used primarily to acknowledge that a task has been completed.

Don't

Make the request for user action the primary message on a Toast. If you need user action, use an ModalAlert or Callout instead.

Variants

How to display

Toasts should be displayed in the center of the viewport, opposite the main navbar (e.g. at the top of the viewport on mobile, bottom of the viewport on desktop). Though not implemented here, Toasts are meant to be ephemeral and disappear after a few seconds.

Text-only

A simple, generic acknowledgment after an action is taken. These should not be actionable.

Success

With an icon that denotes a more important change, like a password update. These should not be actionable.

Processing

A toast with a loading spinner or other progress indicator that disappears once the process is complete.

Error

Used rarely for connection issues or unknown errors where we don’t want to completely block the users flow, but want the message to persist if the user goes to another surface. Providing a way to solve the error or get help is recommended.

Message

The text prop accepts either a string or Text. Use a string for guide toasts without any visual style. Toast will handle the text style and adherence to design guidelines. Regular strings are subject to two-line truncation.

If confirmation toast's text with more complex style is required, such as bold text, inline links, or no truncation, use Text to wrap your message with any additional Text or Link usages contained within. When passing in your own Text component for text, do not specify color on Text. Toast will automatically pick the correct text color for the given type.

Primary action

As a secondary element, to drive users to another surface, or change a recently completed action

As a secondary element, to drive users to another surface.

Image

With an image for Pin or Board actions.

Avatar

With an Avatar for Profile or Pinner-related messaging. An optional link be included. When there’s a link on mWeb, the entire toast is tapable, using TapArea.

Icon

For when an icon is needed to represent content that isn’t a pin or a profile.

Dismissable

Duration and timing

Toasts should be on screen for a minimum of 5 seconds; this gives most people enough time to read and act. Please note that a separate Toast manager must be implemented in order to handle duration and animation.

Once a toast is triggered, allow for a cooldown period of about 7 seconds before the toast can be triggered again. This will prevent multiple toasts from appearing.

Writing

Do
  • Consider internationalization and how other languages may be take up more space.
  • Be brief and concise.
  • Use conversational language.
Don't
  • Use lengthy, technical jargon or local idioms that will be hard to translate to other languages.

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma across all platforms.
Responsive Web
Ready
Component is available in code for web and mobile web.
iOS
Component is not currently available in code for iOS.
Android
Component is not currently available in code for Android.

Alert Modal
An ModalAlert is a simple modal dialog used to alert a user of an issue, or to request confirmation after a user-generated action. ModalAlert overlays and blocks Page content until it is dismissed by the user.

Modal
A generic, customizable container for modals that aren’t used as alerts or acknowledgements and need more functionality like form fields.

PopoverEducational
PopoverEducational are used to educate users about a particular element on the screen, like a button or new UI control.

Tooltip
Tooltip provides helpful information regarding an interactive UI element, typically an IconButton. It is displayed on hover or focus of a UI element, and disappears on mouse out or blur.

Upsell
Upsell banners are used for paid upgrades, free trials, or marketing promotions.

Callout
Callouts are used at the top-most level of a page to communicate highest-priority information that applies to the entire page or surface. Callouts can be dismissed and are also actionable.

Edit page on GitHub
; Opens a new tab