Toast

<Toast onDismiss={() => alert('dismissed')} variant="neutral">
    Your function is currently being deployed.
</Toast>

Use a Toast to respond to a user action. The type of Toast you use depends on the situation:

• Success. Confirm a successful or completed action.
• Warning. Help a user avoid a future issue that might happen based on their action.
• Error. Communicate an issue that's preventing a user from completing their current action.
• Neutral. Let a user know that an asynchronous process has been triggered based on their action, especially if they have to wait for the process to finish before continuing a workflow. This could include a large download or a request that's been sent to a third party.

To decide whether a Toast is the appropriate component, refer to the Alerts vs. Callouts vs. Toasts vs. Help Text guide.

Toasts appear over content on a page and stack vertically. All Toasts have a close button so that users can dismiss any Toasts that may be blocking underlying page content.

If you make a Toast automatically time out, consider users that have different reading speeds, vision levels, and literacy levels (more details in the research insight below).

We recommend giving users about 500 milliseconds per word. For short Toasts (about 5–10 words), give users about 2,000–4,000 milliseconds to read the toast message. For Toasts at our max suggested length of 140 characters, that's about 30,000 milliseconds for about 55 English words. In this case, consider not making the Toast automatically time out since the longer content length could suggest that there's information worth persisting for the customer.

In addition to reading time, consider the time users need to make a decision based on the message. If a Toast has any interactive element in it, like a link or button, don't add an automatic time-out to the Toast.

Don't use Toasts to communicate dynamically changing content, including progress bars. Toasts have ARIA role=status and trigger a status update to assistive technology each time the content changes, potentially annoying users. Use a Non-Modal Dialog or Modal, or show the changing content on the underlying page instead.

Here are ways that you can compose neutral, warning, error, success, and dismissible Toasts.

The Toaster is a convenient way to manage showing and dismissing Toasts. The Toaster comes in two parts:

• A useToaster hook that handles adding, removing, auto dismissing and state.
• A <Toaster /> component that handles rendering Toasts into the DOM.

The easiest way to use the Toaster is to use the useToaster hook. It will handle adding and removing a Toast and can be used to set automatic time-outs. The useToaster hook will then return the props needed to render the Toasts within the Toaster component.

useToaster returns 3 things:

• An array of toasts to be rendered in the DOM.
• A push method used to add a Toast to the Toaster.
• A pop method used to remove a Toast from the Toaster via its ID.

Below is a form you can use to create Toasts dynamically using the Toaster. The form data is used to push a new Toast to the Toaster.

You can push a Toast to the Toaster stack based on any action or event. In this example it's based on a button click:

const MyComponent = () => {
  const toaster = useToaster();

  const handleClick = () => {
    toaster.push({
      message: 'Selection was successfully saved to your profile',
      variant: 'success',
    })
  }

  return(
    <>
      <Button variant="primary" onClick={handleClick}>
        Add a toast
      </Button>
      <Toaster left={['space40', 'unset', 'unset']} {...toaster} />
    </>
  )
}

You can optionally provide an id to a Toast when you push it to the stack. The ID can then be used to programmatically pop the Toast from the stack:

toaster.push({
  message: 'Selection was successfully saved to your profile',
  variant: 'success',
  id: 'custom_id',
})

toaster.pop('custom_id')

When providing your own custom ID, make sure they are unique.

You can optionally provide a time-out to a Toast, after which the Toast is automatically dismissed. This can be done by setting a dismissAfter value. The value must be a valid time-out, set in milliseconds.

toaster.push({
  message: 'Selection was successfully saved to your profile',
  variant: 'success',
  id: 'custom_id',
  dismissAfter: 4000
})

Add an automatic time-out if all these conditions are true:

• The user wouldn't need to remember or copy the information in order to continue with their current flow, or any future flow.
• The Toast doesn't have any interactive content, such as a link or button.

We recommend giving users about 500 milliseconds per word before timing out a Toast.

The <Toaster /> component handles rendering the Toasts it is passed via props. It handles how the Toast enters and leaves the UI.

If you pass it the returned state of the useToaster hook, state, pushing, popping, and handling browser window time-outs is taken care of for you.

const toaster = useToaster();

return <Toaster left={['space40', 'unset', 'unset']} {...toaster} />;

Use a neutral Toast to communicate that a background process was triggered based on their action, especially if they have to wait for the process to finish before continuing a flow.

You may use the Text primitive as a child of Toast, but if you do, be sure to pass color="inherit" for neutral Toasts.

<Toast onDismiss={() => alert('dismissed')} variant="neutral">
    Your function is currently being deployed.
</Toast>

Use a success Toast to confirm a successful or completed action. Avoid using the word "successfully" in the message - it's redundant.

If a creation flow has 2 steps, where a user creates an object then edits edits it, use a success Toast after each step.

Occasionally, it's helpful to embed a link or action in a success Toast.

• Creation flow: Consider whether it makes sense to offer a link to the newly created object.

• Undo: Provide an "undo" action if it's easily and safely reversible and you can take the user back to the previous state. For example, offer an undo action if:

  • A user submitted a short form that updates something. Undoing the action can take them back to their filled form with any sensitive fields cleared.
  • A user deleted non-sensitive information we'd want them to easily retrieve.

You may use the Text primitive as a child of Toast, but if you do, be sure to pass color="inherit" for success Toasts.

<Toast onDismiss={() => alert('dismissed')} variant="success">
    Your email address has been updated. You can view your profile <Anchor href="#">here</Anchor>.
</Toast>

Use a warning Toast to help a user avoid a potential future issue that might happen based on their action. If the user can take an immediate action to avoid the issue, provide a way to do that. In most cases, a warning Toast lets users know that their current action completed but may have triggered a related issue.

Be cautious when using a warning Toast because they can be stressful for a user to see. If the information you're trying to convey is not very critical, consider using a neutral Toast instead.

You may use the Text primitive as a child of Toast, but if you do, be sure to pass color="inherit" for warning Toasts.

<Toast onDismiss={() => alert('dismissed')} variant="warning">
    The phone number has been deleted. Functions still using this phone number may fail. Verify there are no functions tied to that number <Anchor href="#">here</Anchor>.
</Toast>

Use an error Toast to communicate a brief, easily comprehended issue that's preventing them from completing their current action. Provide a way to resolve the issue either in the underlying page content or in the Toast.

Consider using a Callout instead if:

• The issue or the resolution requires more than two short sentences.
• The error is specific to a particular part of the page, since Toasts do not appear in contextually relevant locations on the page.

Never allow an error Toast to automatically time out.

For additional guidance on how to compose error messages, refer to the error state pattern.

You may use the Text primitive as a child of Toast, but if you do, be sure to pass color="inherit" for error Toasts.

<Toast onDismiss={() => alert('dismissed')} variant="error">
    There was an error when deleting the profile. Please try again.
</Toast>

Use the left prop on Toaster and Toast Container so that you can use your app's breakpoints to set the placement of your Toasts.

import {Toast, Toaster, ToastContainer} from '@twilio-paste/core/toast';

const ToastWithToaster = () => {
  const toaster = useToaster();
  return <Toaster left={['space40', 'unset', 'unset']} {...toaster} />;
};

const ToastWithContainer = () => {
  return (
    <ToastContainer left={['space40', 'unset', 'unset']}>
      <Toast>I am toast</Toast>
    </ToastContainer>
  );
};

To internationalize a Toast, simply pass different text as children to the Toast. The only exceptions to this are the labels for both the dismiss Button and the variant icons. To change the dismiss Button's label text, use the i18nDismissLabel prop. To change the label of a variant's icon, use the matching i18n prop for the variant. For a success variant, for example, set the i18nSuccessLabel prop.

const I18nExample = () => {
  return (
    <Toast variant="neutral" i18nDismissLabel="Cerrar notificacion" i18nNeutralLabel="(informacion)">
      Soy una notificación
    </Toast>
  );
};

render(<I18nExample />);

Keep the Toast text brief, scannable, and specific to the current user action. Only include the highest priority information and aim for no more than 140 characters. Success Toasts generally run about 50 characters long, while all other alerts might run about 100 characters long. It's okay to exclude articles to keep messages concise.

Compose a Toast with:

• Title (optional). Bold the text at the beginning of the Toast. The title should be concise and convey the essence of the issue.
• Body text. Use the default text style. Do not repeat information contained in a title. Limit body text to 1-2 sentences.
• Full punctuation. Use periods after full sentences. Avoid using exclamation points.

If the user needs to take action on another page, or more information would be helpful to them, use an Anchor. Be cautious about using a button in a Toast since it should be used only to trigger an action. If you must use a Button, use a small secondary button.

Alert

• Alerts communicate information relevant at the system level.
• Do not use Alerts in response to user action.

Callout

• Callouts communicate information particular to a section of a page, or information that applies to a whole page.
• Use a Callout when there are multiple pieces of information to convey. For example, an error summary.
• Callouts can result from a user action, but don’t have to. Therefore, they can include either static or contextual content.

Toast

• Toasts communicate brief, easily comprehended messages.
• Toasts generally result from a user action.
• If the message is contextual or specific to a particular part of a page, consider Help Text or a Callout.
• Do not use a Toast if the message is longer than two sentences (~140 characters). Use a Callout instead.
• Do not use a Toast if there is more than one anchor or button. Use a Callout instead.

Help Text

• Help Text communicates contextual responses.
• Help Text can result from a user action, but don’t have to.