Toast

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.

Approve request

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>
  );
};

Displaying an error?

When displaying an error, consider using an Alert instead, which displays persistently on the page.

Descriptions

Provide a description to add more context to your toast.

Send invite

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>
  );
};

Avoid inline links

Avoid using inline links within descriptions. Instead, use an action with href to link to a page.

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.

Send error message

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.

Verify user

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>
  );
};

Don’t use duotone or filled icons

All icons for Toast should be imported from @fortawesome/pro-regular-svg-icons.

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.

Delete Scribe

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

Show toastDismiss toast

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

Most often, the useToast hook is how you’ll trigger a toast. useToast returns two objects: toast and dismiss.

Prop	Type	Default
dismiss	(toastId?: string) => void
toast	(props: ToastProps) => { id: string; dismiss: () => void; update: (props: ToastProps) => void }

Toast

These props can be passed to the toast function from useToast.

Prop	Type	Default
title	string
action	ToastActionElement
description	string
duration	number	5000
icon	IconDefinition	faInfoCircle
type	"foreground""background"	"foreground"
variant	"info""success""warning""error"	"info"

Less common props are also available: see Radix UI docs for the full list.

ToastAction

Inherits all props from Button.

Prop	Type	Default
altText	string
asChild	boolean	false
href	string
onClick	() => void
target	string
variant	"primary""secondary""danger""ghost""link"	"primary"