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:

Web:

iOS:

Android:

A11y:

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.
`helperLink`	`{\| 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

Partially ready

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

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

import { useState } from 'react';
import { Box, Toast, Button, Layer, Text, Link, Image } 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%)',
              },
            }}
            width="100%"
            paddingX={1}
            position="fixed"
            display="flex"
            justifyContent="center"
          >
            <Toast
              primaryAction={{
                accessibilityLabel: 'Test',
                label: 'Undo',
                size: 'lg',
              }}
              text={
                <Text inline>
                  Saved to{' '}
                  <Link
                    display="inlineBlock"
                    target="blank"
                    href="https://www.pinterest.com/search/pins/?q=home%20decor"
                  >
                    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
      justifyContent="center"
      alignItems="center"
      width="100%"
      height="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
      justifyContent="center"
      alignItems="center"
      width="100%"
      height="100%"
    >
      <Toast type="success" text="Password updated" />
    </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
      justifyContent="center"
      alignItems="center"
      width="100%"
      height="100%"
    >
      <Toast type="progress" text="Updating" />
    </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
      justifyContent="center"
      alignItems="center"
      width="100%"
      height="100%"
    >
      <Toast
        type="error"
        text="You are not connected to the Internet."
        helperLink={{
          text: 'Retry',
          accessibilityLabel: 'Retry connecting to the Internet',
          href: '#',
        }}
      />
    </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, Toast, Link, Text } from 'gestalt';

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

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

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

Primary action

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

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

export default function Example() {
  return (
    <Flex
      justifyContent="center"
      alignItems="center"
      width="100%"
      height="100%"
    >
      <Toast
        primaryAction={{ accessibilityLabel: 'Edit your Pin', label: 'Edit' }}
        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"
            />
          ),
        }}
        text="Saved to your profile!"
      />
    </Flex>
  );
}

Helper link

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

import { Flex, Toast } from 'gestalt';

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

Image

With an image for Pin or Board actions.

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

export default function Example() {
  return (
    <Flex
      justifyContent="center"
      alignItems="center"
      width="100%"
      height="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 { Flex, Toast, Avatar } from 'gestalt';

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

Icon

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

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

export default function Example() {
  return (
    <Flex
      justifyContent="center"
      alignItems="center"
      width="100%"
      height="100%"
    >
      <Toast
        primaryAction={{ accessibilityLabel: 'Edit', label: 'Edit' }}
        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
      justifyContent="center"
      alignItems="center"
      width="100%"
      height="100%"
    >
      <Toast
        text="Your Pin was saved"
        dismissButton={{ onDismiss: () => {} }}
      />
    </Flex>
  );
}

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

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

Toast

also known as Snackbar

Props

Usage guidelines

Accessibility

Icons

Duration

Localization

Best practices

Variants

How to display

Text-only

Success

Processing

Error

Message

Primary action

Helper link

Image

Avatar

Icon

Dismissable

Duration and timing

Writing

Component quality checklist

Related