Skip to Content
Toast

Toast

Display a brief notification.

#

Documentation

#

Usage

Use toaster.create() to add toasts. The method takes two arguments message and options.

"use client"; import { Button, toaster } from "@optiaxiom/react"; export function App() { return ( <Button onClick={() => toaster.create("This is an example toast message.")}> Create Toast </Button> ); }

#

Appearance

Use the intent option in the second argument to select between the different toast types.

"use client"; import { Button, Group, toaster } from "@optiaxiom/react"; export function App() { return ( <Group flexWrap="wrap" gap="16"> {( ["danger", "information", "neutral", "success", "warning"] as const ).map((intent) => ( <Button key={intent} onClick={() => toaster.create("This is an example toast message.", { intent }) } > {intent} toast </Button> ))} </Group> ); }

#

Action

Use the action and onAction options to include a short action button associated with the toast.

Toasts with an action stay open 1.5 times the provider’s duration. They still close on their own, so keep whatever the action does reachable elsewhere too. For undo, apply the change right away and make the action restore it, like the demo below.

Task in-progress

"use client"; import { IconTrashCan } from "@optiaxiom/icons"; import { Button, Group, Text, toaster } from "@optiaxiom/react"; import { useState } from "react"; export function App() { const [status, setStatus] = useState("in-progress"); return ( <Group gap="16"> <Text>Task {status}</Text> <Button appearance="danger-outline" disabled={status === "deleted"} icon={<IconTrashCan />} onClick={() => { setStatus("deleted"); toaster.create("Task Deleted", { action: "Undo", onAction: () => setStatus("in-progress"), }); }} > Delete </Button> <Button disabled={status !== "deleted"} onClick={() => setStatus("in-progress")} > Restore </Button> </Group> ); }

#

Dismiss

Use toaster.remove() to remove toasts. The create() method returns a unique ID for the toast which can then be passed to the remove() method.

"use client"; import { Button, toaster } from "@optiaxiom/react"; export function App() { return ( <Button onClick={async () => { const id = toaster.create("Saving task"); // simulate network request await new Promise((resolve) => setTimeout(resolve, 3_000)); toaster.remove(id); toaster.create("Could not save task", { intent: "danger" }); }} > Create Toast </Button> ); }

#

When not to use a toast

A toast briefly confirms something that already happened. Use something else for:

  • Undo windows that hold a change back: apply the change right away and make the toast action restore it, without a confirmation dialog beforehand.
  • Progress on running work: show it on the control that started it, with Button loading or an inline Spinner.
  • Long or persistent messages: use Banner or Alert.

Alert

Show inline messages about important or time-sensitive changes.

Banner

Display a prominent message at the top of the screen.

#

Props

#

ToastProvider

import { ToastProvider } from "@optiaxiom/react"; // or import { ToastProvider } from "@optiaxiom/react/toast";

Supports all Box props in addition to its own. Renders a <div> element.

Prop

asChild

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read the Composition guide for more details.

false | true

children

undefined

className

string

container

An optional container where the portaled content should be appended.

null | Element | DocumentFragment

duration

Time in milliseconds that each toast should remain visible for. @defaultValue 5000

number

Default: 5000

hotkey

The keys to use as the keyboard shortcut that will move focus to the toast viewport. @defaultValue [‘F8’]

string[]

label

An author-localized label for each toast. Used to help screen reader users associate the interruption with a toast. @defaultValue ‘Notification’

string

position

Control where in the screen toasts will be placed.

"bottom" | "top" | "bottom-left" | "bottom-right" | "top-left" | "top-right"

Default: top-right

swipeDirection

Direction of pointer swipe that should close the toast. @defaultValue ‘right’

"left" | "right" | "up" | "down"

swipeThreshold

Distance in pixels that the swipe must pass before a close is triggered. @defaultValue 50

number

toaster

An instance of toaster returned from the createToaster method.

Toaster

#

Accessibility

#

Announcements

  • Toasts are announced to screen readers when they appear. Keep the message short and self-contained.
  • Keyboard users press F8 to move focus to the toasts. The timer pauses while focus or the pointer is on a toast.
  • A toast closes on its own, so keep whatever its action does reachable elsewhere too.

#

Changelog

#

0.1.0

  • Added component
Last updated on