Toast

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

Responsive:

Ready

Adaptive:

N/A

Props

Component props
Name	Type	Default
`text` Required	`string \| ReactElement`	-
	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.
`helperLink`	`{ text: string; accessibilityLabel: string; href: string; onClick?: (arg1: { event: React.MouseEvent<HTMLAnchorElement> \| React.KeyboardEvent<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?: ComponentProps<typeof ButtonLink>["onClick"]; rel?: ComponentProps<typeof Link>["rel"]; role: "link"; size?: ComponentProps<typeof Button>["size"]; target?: ComponentProps<typeof Link>["target"]; } \| { accessibilityLabel: string; label: string; onClick: ComponentProps<typeof Button>["onClick"]; role?: "button"; size?: ComponentProps<typeof Button>["size"]; }`	-
	Adds an optional button for user interaction. Generally not recommended given the ephemeral nature of Toasts.
`thumbnail`	`{ image: ReactElement } \| { avatar: ReactElement } \| { icon: ReactElement }`	-
	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 BannerUpsell instead.
For errors that relate to a specific section or page. Use BannerCallout(/web/bannercallout) or BannerSlim(/web/bannerslim) instead.
To guide or educate the user. Use Popover(/web/popover) or Tooltip(/web/tooltip) instead.

Best practices

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.

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

Don't

Stack multiple toasts as that will block the user.

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.

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.

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 BannerCallout instead.

Accessibility

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.

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.

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

Note that dismissButton.accessibilityLabel is optional as DefaultLabelProvider provides default strings. Use custom labels if they need to be more specific.

Toast depends on DefaultLabelProvider for internal text strings. Localize the texts via DefaultLabelProvider. Learn more

import { DefaultLabelProvider, Flex, Toast } from 'gestalt';

export default function Example() {
  return (
    <DefaultLabelProvider
      labels={{
        Toast: {
          accessibilityDismissButtonLabel: 'Den Toast verwerfen',
          accessibilityIconSuccessLabel: 'Erfolgsmeldung',
          accessibilityIconErrorLabel: 'Fehlermeldung',
          accessibilityProcessingLabel: 'Nachricht bearbeiten',
        },
      }}
    >
      <Flex
        alignItems="center"
        height="100%"
        justifyContent="center"
        width="100%"
      >
        <Toast
          dismissButton={{ onDismiss: () => {} }}
          text="Passwort aktualisiert"
          type="success"
        />
      </Flex>
    </DefaultLabelProvider>
  );
}

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.

import { useState } from 'react';
import { Box, Button, Image, Layer, Link, Text, Toast } from 'gestalt';

export default function Example() {
  const [showToast, setShowToast] = useState(false);

  return (
    <Box padding={3}>
      <Button
        onClick={() => setShowToast((currVal) => !currVal)}
        text={showToast ? 'Close toast' : 'Show toast'}
      />

      {showToast && (
        <Layer>
          <Box
            dangerouslySetInlineStyle={{
              __style: {
                bottom: 50,
                left: '50%',
                transform: 'translateX(-50%)',
              },
            }}
            display="flex"
            justifyContent="center"
            paddingX={1}
            position="fixed"
            width="100%"
          >
            <Toast
              primaryAction={{
                accessibilityLabel: 'Test',
                label: 'Undo',
                size: 'lg',
                role: 'button',
                onClick: () => {},
              }}
              text={
                <Text inline>
                  Saved to{' '}
                  <Link
                    display="inlineBlock"
                    href="https://www.pinterest.com/search/pins/?q=home%20decor"
                    target="blank"
                  >
                    Home decor
                  </Link>
                </Text>
              }
              thumbnail={{
                image: (
                  <Image
                    alt="Modern ceramic vase pin."
                    naturalHeight={564}
                    naturalWidth={564}
                    src="https://i.ibb.co/Lx54BCT/stock1.jpg"
                  />
                ),
              }}
            />
          </Box>
        </Layer>
      )}
    </Box>
  );
}

Text-only

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

import { Flex, Toast } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Toast text="Pin deleted" />
    </Flex>
  );
}

Success

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

import { Flex, Toast } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Toast text="Password updated" type="success" />
    </Flex>
  );
}

Processing

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

import { Flex, Toast } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Toast text="Updating" type="progress" />
    </Flex>
  );
}

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.

import { Flex, Toast } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Toast
        helperLink={{
          text: 'Retry',
          accessibilityLabel: 'Retry connecting to the Internet',
          href: '#',
        }}
        text="You are not connected to the Internet."
        type="error"
      />
    </Flex>
  );
}

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.

import { Flex, Link, Text, Toast } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      direction="column"
      gap={2}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Toast text="Signed as Three Crafty Ladies" />
      <Toast
        text={
          <Text inline>
            Saved to{' '}
            <Link
              display="inlineBlock"
              href="https://www.pinterest.com/search/pins/?q=home%20decor"
              target="blank"
            >
              Home decor
            </Link>
          </Text>
        }
      />
    </Flex>
  );
}

import { Box, Flex, Image, Toast } from 'gestalt';

export default function Example() {
  return (
    <Box height="100%" paddingY={4} width="90%">
      <Flex
        alignItems="center"
        direction="column"
        gap={2}
        height="100%"
        justifyContent="center"
        width="100%"
      >
        <Toast
          primaryAction={{
            accessibilityLabel: 'Undo',
            label: 'Undo',
            role: 'button',
            onClick: () => {},
          }}
          text="Your account admin rights were successfully saved"
          thumbnail={{
            image: (
              <Image
                alt="Modern ceramic vase pin."
                naturalHeight={564}
                naturalWidth={564}
                src="https://i.ibb.co/Lx54BCT/stock1.jpg"
              />
            ),
          }}
        />
        <Toast
          dismissButton={{ onDismiss: () => {} }}
          helperLink={{
            text: 'Go to settings',
            accessibilityLabel: 'Go to settings',
            href: '#',
          }}
          text="Your account admin rights were successfully saved."
        />
      </Flex>
    </Box>
  );
}

Primary action

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

import { Flex, Image, Toast } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Toast
        primaryAction={{
          accessibilityLabel: 'Edit your Pin',
          label: 'Edit',
          role: 'button',
          onClick: () => {},
        }}
        text="Saved to your profile!"
        thumbnail={{
          image: (
            <Image
              alt="Pink flamingo drawing pattern on a dark green background"
              naturalHeight={1}
              naturalWidth={1}
              src="https://i.pinimg.com/564x/39/b7/5e/39b75ec3211d0efe8e727da2c2af1966.jpg"
            />
          ),
        }}
      />
    </Flex>
  );
}

Helper link

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

import { Flex, Toast } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Toast
        dismissButton={{ onDismiss: () => {} }}
        helperLink={{
          text: 'Go to settings',
          accessibilityLabel: 'Go to settings',
          href: '#',
        }}
        text="Your address was updated."
      />
    </Flex>
  );
}

Image

With an image for Pin or Board actions.

import { Flex, Image, Toast } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Toast
        text="Pin promoted"
        thumbnail={{
          image: (
            <Image
              alt="A regular sandwich with tomato, lettuce, and cheese."
              naturalHeight={564}
              naturalWidth={564}
              src="https://i.pinimg.com/564x/90/e2/17/90e217ea5513fcfcada465c763250b7e.jpg"
            />
          ),
        }}
      />
    </Flex>
  );
}

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.

import { Avatar, Flex, Toast } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Toast
        text="Switched to Mara Ibrahim"
        thumbnail={{
          avatar: (
            <Avatar name="Keerthi" src="https://i.ibb.co/ZfCZrY8/keerthi.jpg" />
          ),
        }}
      />
    </Flex>
  );
}

Icon

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

import { Flex, Icon, Toast } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Toast
        primaryAction={{
          accessibilityLabel: 'Edit',
          label: 'Edit',
          role: 'button',
          onClick: () => {},
        }}
        text="Save the link from your clipboard?"
        thumbnail={{
          icon: <Icon accessibilityLabel="Go to next steps" icon="link" />,
        }}
      />
    </Flex>
  );
}

Dismissable

import { Flex, Toast } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Toast
        dismissButton={{ onDismiss: () => {} }}
        text="Your Pin was saved"
      />
    </Flex>
  );
}

Responsive

Toast is responsive to different devices to preserve a great usability experience and consistency with other components.

Writing

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 for web and mobile web.
Responsive Web	Ready	Component responds to changing viewport sizes in web and mobile web.

Internal documentation

PDocs available

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.

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

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

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.

Edit page on GitHub

Toast

also known as Snackbar

Props

Usage guidelines

Best practices

Accessibility

Duration

Localization

Variants

How to display

Text-only

Success

Processing

Error

Message

Primary action

Helper link

Image

Avatar

Icon

Dismissable

Responsive

Writing

Component quality checklist

Internal documentation

Related