Toast

A succinct message that is displayed temporarily.

Usage

To display a toast, import the useToast hook and call the toast function. The only required prop is title. By default, the toast will render a close button on hover and an icon according to the variant.

import { Button } from "stylus-ui/Button";
import { useToast } from "stylus-ui/Toast";

export default () => {
  const { toast } = useToast();

  return (
    <Button
      variant="secondary"
      onClick={() => toast({ title: "Access request approved" })}
    >
      Approve request
    </Button>
  );
};

Descriptions

Provide a description to add more context to your toast.

import { useToast } from "stylus-ui/Toast";
import { Button } from "stylus-ui/Button";

export default () => {
  const { toast } = useToast();

  return (
    <Button
      variant="secondary"
      onClick={() =>
        toast({
          title: "Invite sent",
          description: "Email sent to 6 members.",
          variant: "success",
        })
      }
    >
      Send invite
    </Button>
  );
};

Variants

Toasts can have different variants to indicate the nature of the message: info (default), success, warning, or error. Each variant will display a default icon associated with that status. You can also set a custom icon.

import { useToast } from "stylus-ui/Toast";
import { Button } from "stylus-ui/Button";

export default () => {
  const { toast } = useToast();

  return (
    <Button
      variant="secondary"
      onClick={() =>
        toast({
          title: "Something went wrong",
          description: "We couldn't complete your request. Try again later.",
          variant: "error",
        })
      }
    >
      Send error message
    </Button>
  );
};

Icons

Override the default icon for a toast by passing a Font Awesome icon to the icon prop.

import { useToast } from "stylus-ui/Toast";
import { Button } from "stylus-ui/Button";
import { faUserAlien } from "@fortawesome/pro-regular-svg-icons";

export default () => {
  const { toast } = useToast();

  return (
    <Button
      variant="secondary"
      onClick={() =>
        toast({
          title: "User not recognized",
          description: "Couldn't verify the user's identity.",
          icon: faUserAlien,
          variant: "warning",
        })
      }
    >
      Verify user
    </Button>
  );
};

Actions

To display actions on a toast, import ToastAction and ToastActionGroup from stylus-ui/Toast, and pass them to the action prop. ToastAction accepts the same props as <Button>. Each ToastAction requires an altText prop for accessibility.

import { useToast, ToastAction, ToastActionGroup } from "stylus-ui/Toast";
import { Button } from "stylus-ui/Button";

export default () => {
  const { toast } = useToast();

  return (
    <Button
      variant="secondary"
      onClick={() =>
        toast({
          title: "Scribe deleted",
          description: "Your Scribe has been deleted.",
          action: (
            <ToastActionGroup>
              <ToastAction altText="Undo action">Undo</ToastAction>
              <ToastAction altText="Dismiss notification" variant="secondary">
                Dismiss
              </ToastAction>
            </ToastActionGroup>
          ),
        })
      }
    >
      Delete Scribe
    </Button>
  );
};

Dismissing toasts

import { useState } from "react";
import { useToast } from "stylus-ui/Toast";
import { Button } from "stylus-ui/Button";

export default () => {
  // Initialize the toast and dismiss functions
  const { toast, dismiss } = useToast();
  const [toastId, setToastId] = useState(null);

  const showToast = () => {
    // Save the { id } from the toast function
    const { id } = toast({
      title: "Loading…",
      description: "This is taking a little longer than normal.",
    });

    setToastId(id);
  };

  return (
    <div className="flex gap-2">
      <Button variant="secondary" onClick={showToast}>
        Show toast
      </Button>
      <Button
        variant="secondary"
        onClick={
          // Dismiss the toast using the id
          () => dismiss(toastId)
        }
      >
        Dismiss toast
      </Button>
    </div>
  );
};

API Reference

`useToast`

Hook that provides the imperative API for creating and dismissing toasts. Use this inside a component tree wrapped in ToastProvider.

Returns:

Name	Type	Description
`toast`	`(options) => { id, dismiss, update }`	Creates a toast. Returns an object with `id`, `dismiss`, and `update`.
`dismiss`	`(toastId?: string) => void`	Dismisses the toast with the given `id`, or all toasts when no id is passed.

toast(options) options:

Prop	Type	Required	Default	Description
`title`	`ReactNode`	Yes	—	Main heading text.
`description`	`string \| ReactNode`	No	—	Optional body text below the title.
`variant`	`"info" \| "success" \| "warning" \| "error"`	No	`"info"`	Visual style and default icon.
`icon`	`IconDefinition`	No	by variant	Font Awesome icon (e.g. from `@fortawesome/pro-regular-svg-icons`).
`action`	`ReactElement` (e.g. `ToastActionGroup` with `ToastAction`s)	No	—	Action buttons (e.g. “Undo”, “Dismiss”).
`onDismiss`	`() => void`	No	—	Called when the user dismisses the toast.

Example:

const { toast, dismiss } = useToast();

// Show a toast and capture its id for later dismissal
const { id } = toast({ title: "Saved.", variant: "success" });
dismiss(id); // dismiss that toast
dismiss(); // dismiss all toasts

`ToastProvider`

`duration`

number = 5000

Time in milliseconds that each toast should remain visible for.

`label`

string = "Notification"

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

`swipeDirection`

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

Direction of pointer swipe that should close the toast.

`swipeThreshold`

number = 50

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

`ToastViewport`

`asChild`

boolean

`hotkey`

string[] = "['F8']"

The keys to use as the keyboard shortcut that will move focus to the toast viewport.

`label`

string = "Notifications ({hotkey})"

An author-localized label for the toast viewport to provide context for screen reader users when navigating page landmarks. The available {hotkey} placeholder will be replaced for you.

`ToastActionGroup`

Groups multiple ToastAction buttons in a horizontal row inside a toast.

`children`

Required

ReactNode

One or more ToastAction elements.

`ToastAction`

`altText`

Required

string

A short description for an alternate way to carry out the action. For screen reader users who will not be able to navigate to the button easily/quickly. @example @example

`asChild`

boolean

`disabled`

boolean = false

Disable the button, preventing it from being clicked.

`dropdown`

boolean = false

Display a caret icon to indicate that this button opens a dropdown menu.

`href`

string

Navigate to a URL when clicked. If provided, the button will render as an anchor element.

`icon`

IconDefinition

Display an icon at the start of the button.

`iconEnd`

IconDefinition

Display an icon at the end of the button.

`iconEndProps`

Omit<Omit<IconProps, "ref"> & RefAttributes<SVGSVGElement>, "icon">

Props to pass to the icon component at the end of the button.

`iconProps`

Omit<Omit<IconProps, "ref"> & RefAttributes<SVGSVGElement>, "icon">

Props to pass to the icon component at the start of the button.

`loading`

boolean = false

Display a loading indicator to the left of the button.

`onClick`

MouseEventHandler<HTMLButtonElement> & MouseEventHandler<HTMLButtonElement | HTMLAnchorElement> | MouseEventHandler<HTMLButtonElement> & MouseEventHandler<HTMLAnchorElement> & MouseEventHandler<HTMLButtonElement | HTMLAnchorElement>

Click handler for the action.

`target`

string

Target for link actions (e.g. “_blank”).

`variant`

"primary" | "secondary" | "ghost" | "danger" = "info"

The variant of the button.

primary: A primary button with a brand gradient background. Limit usage to one per page.
secondary: A secondary button with a plain stroke. Use for most buttons.
ghost: A ghost button with a transparent background. Use for buttons that should blend into the background.
danger: A danger button with a red background. Use for destructive actions.

`Toast`

A succinct message that is displayed temporarily.

`title`

Required

string

Main heading text.

`asChild`

boolean

`defaultOpen`

boolean

`description`

string | ReactNode

Optional body text or node below the title.

`duration`

number

Time in milliseconds that toast should remain visible for. Overrides value given to ToastProvider.

`forceMount`

true

Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.

`icon`

IconDefinition

Icon shown at the start; defaults by variant if not set.

`onDismiss`

() => void

Called when the user dismisses the toast (e.g. close button).

`onEscapeKeyDown`

(event: KeyboardEvent) => void

`onOpenChange`

(open: boolean) => void

`onPause`

() => void

`onResume`

() => void

`onSwipeCancel`

(event: SwipeEvent) => void

`onSwipeEnd`

(event: SwipeEvent) => void

`onSwipeMove`

(event: SwipeEvent) => void

`onSwipeStart`

(event: SwipeEvent) => void

`open`

boolean

`type`

"foreground" | "background"

`variant`

"success" | "warning" | "error" | "info" = "info"

Visual style: info, success, warning, or error (affects icon and color).