Skip to main content

Toast

Used to interrupt the user with a short message in response to an action.

Import

import { ToastProvider, useToast } from '@pluralsight/react'

Anatomy

  1. Wrapper
  2. Container
  3. Icon
  4. Heading (optional)
  5. Text
  6. Action Button (optional)
  7. Close Button

Usage

Basic Toast

import { Button, ToastProvider, useToast } from '@pluralsight/react'

function SomeFeatureSection() {
  const toast = useToast()

  function handleShowToast() {
    toast.show({
      text: 'Channel has been bookmarked.',
    })
  }

  return <Button onClick={handleShowToast}>Show Toast</Button>
}

export default function SomePage() {
  return (
    <ToastProvider>
      <SomeFeatureSection />
    </ToastProvider>
  )
}

Toast Status

  1. Info: Brings awareness to important information and sets expectations for the user.
  2. Success: Provides the user with positive confirmation of a successfully performed action or series of steps.
  3. Warning: Helps users avoid error situations and should communicate important or time-sensitive states of the system.
  4. Danger: Alerts of a problem that has already occurred, as a result of user actions.

Toast with "Undo" Button

To display a "undo" button, pass in a onAction callback function to the useToast hook.

const toast = useToast()

function handleShowToast() {
  toast.show({
    text: 'Channel has been bookmarked.',
    onAction: () => {
      // Undo the fetch request
    },
  })
}

Customizing

There are 2 ways to customize the Toast component.

1. Unused Classes

Each component layer of the Toast has a unused class name that can be utilized in your local CSS to customize the Toast at any level.

  1. pando-toast: The element of the Toast.
  2. pando-toast-heading: The heading element of the Toast.
  3. pando-toast-section: The section element of the Toast.
  4. pando-toast-wrapper: The wrapper element of the Toast.
  5. pando-toast-icon-wrapper: The icon wrapper element of the Toast.
  6. pando-toast-close-icon-wrapper: The close button wrapper element of the Toast.
  7. pando-toast-button: The "undo" button element of the Toast.

2. Ejected Toast

For a low-level "ejected" approach, you can use the Headless-styles API to customize the Toast however you prefer while keeping the accessibility behavior.

import {
  getToastContainerProps,
  getToastHeadingProps,
  getToastButtonProps,
} from '@pluralsight/headless-styles'

To learn more about the Headless-styles API, check out the Headless-styles documentation.

Behavior

Toasts are to be used to interrupt the user's task with a short, important, critical or warning message.

Patterns

Do use the Toast when there is an important short message to convey to the user.

Don't use the Toast when you convey a verbose message (larger than 50 characters).

Do keep Toast layout unaltered.

Don't manipulate or add any additional elements/styles to the Toast.

Do use a "undo" action button when the action is reversible.

Don't use a "undo" action button when the action is irreversible.

Usage

Do use sparingly in a user experience.

Don't abuse the use of this Toast by using multiple times at once.

API

ToastProvider

The ToastProvider should NOT be used at the top level of your application. It should be used at the top level of the feature that needs toasts for better performance.

Paramters

This component does not accept any parameters.

useToast

Parameters

interface ToastProps {
  duration?: number
  heading?: string
  text: string
  onAction?: () => void
  sentiment?: 'info' | 'success' | 'warning' | 'danger'
}
  1. duration: The duration of the Toast in milliseconds. Defaults to 8000.
  2. heading: The heading of the Toast.
  3. text: The text of the Toast.
  4. onAction: The callback function of the "undo" button of the Toast.
  5. sentiment: The sentiment of the Toast. Defaults to "info".

Accessibility

The Pando Toast is fully accessible and screen-readable through the following features:

  1. The Toast is announced to the screen reader when it is shown.
  2. The Toast is announced to the screen reader when it is dismissed.
  3. The wrapper element of the Toast has a role="alert" attribute.
  4. The icons of the Toast have aria-hidden="true" attributes.