Toast

Toasts display brief and temporary notifications without interrupting user's experience.

#Example

#Usage

useToast returns stable toast, close, and closeAll actions without subscribing the caller to toast updates. Reusing an id replaces that toast after its exit animation.

#Information

#Success

#Warning

#Error

#Actionable

Toasts can include an optional action button below the message. Use it to offer a way to resolve a problem or suggestion that toast is about.

#Close on action

Pass closeOnAction: false when the action can fail, so the toast stays open and the user can try again. Close it with close(id) once the action succeeds.

#Duration

A toast closes after 4 seconds. Pass duration: Infinity when its action is the only way to undo something, so it stays open until it's dismissed.

#Minimal

Message can be skipped for toasts that don't require detailed explanation.

If toast without a message has an action, it's displayed on the same row as toast title.

#Guidelines

#When to use

• When notifying user about their action that was performed on the same page.
• When toast doesn't contain important information that user has to see.
• When dismissing a toast or not paying attention to it doesn't have negative consequences to user experience.

#When not to use

• If you inform user about important issues, use an alert instead.
• If you notify user about the result of their action taken on a different page than the current one.
• If you need to display errors related to a form, use an alert or an invalid form field.

#Content

• Use sentence case.
• When there's a message in a toast, keep title to 3 words max.

#API

#useToast()

This React hook returns an object with the following properties.

#toast(options)

#options

Type: ToastOptions

Toast options.

#options.id

Type: string

Unique identifier for a toast to make sure only one is displayed at a time.

#options.title

Type: string

Short summary of what happened.

#options.message

Type: string

Extended description of what happened.

#options.variant

Type: "info" | "warning" | "error" | "success"

Determines the appearance of the toast, depending on the intent.

#options.actionText

Type: string

If present, show an action button with this text.

#options.onAction

Type: () => void

Callback for when action button is clicked.

#options.duration

Type: number

How long the toast stays open, in milliseconds. Pass Infinity to keep it open until it's dismissed. Defaults to 4 seconds.

#options.closeOnAction

Type: boolean

Whether clicking the action button closes the toast. Pass false to keep it open, for example until the action succeeds, and close it with close(id). Defaults to true.

#close(id)

#id

Type: string

Close a toast by its ID. ID is a string you provided in a id property when creating a toast.

#closeAll()

Close all toasts.