Toast

Toast notifications with variants and actions

Overview

The Toast component provides a non-intrusive way to display notifications to users. It supports status-dependant variants, optional (though suggested) titles and descriptions, and action buttons. Toasts automatically dismiss after a delay and can be manually dismissed via a close button.

Because toasts disappear automatically after five seconds, it is not recommended to make any actions surfaced within them solely available in the toast. For example, this could be used to give users an opportunity to undo their previous action, but the undo action should also be made available outside of the toast component.

Variants

When title is present, toasts display variant-specific icons by default.

Default

Danger

Warning

Success

With Action

Usage

Import the components and hooks:

import { ToastRoot, useToast } from "@eqtylab/equality";

First, add the ToastRoot component to your application root:

function App() {
  return (
    <>
      {/* Your app content */}
      <ToastRoot />
    </>
  );
}

Basic usage with the useToast hook:

function MyComponent() {
  const { toast } = useToast();

  const handleClick = () => {
    toast({
      title: "Success",
      description: "Your changes have been saved.",
      variant: "success",
    });
  };

  return <button onClick={handleClick}>Show Toast</button>;
}

Props

Name	Description	Type	Default	Required
`variant`	Visual style of the toast with default icon	`default`, `danger`, `warning`, `success`	`default`	❌
`title`	Title text displayed with an icon	`React.ReactNode`	-	❌
`description`	Main message content	`React.ReactNode`	-	❌
`icon`	Custom icon (string for Lucide icon name or React element, null to disable)	`string \| React.ReactElement \| null`	Variant-specific icon	❌
`action`	Action button element	`ToastActionElement`	-	❌
`open`	Control the open state	`boolean`	`true`	❌
`onOpenChange`	Callback when open state changes	`(open: boolean) => void`	-	❌

Toast Instance Methods

The toast function returns an object with the following methods:

Method	Description	Type
`id`	Unique identifier for the toast	`string`
`dismiss`	Function to manually dismiss the toast	`() => void`
`update`	Function to update the toast properties	`(props: ToasterToast) => void`

Examples

Basic Toast

const { toast } = useToast();

toast({
  description: "Your changes have been saved.",
});

Toast with Title and Variant

toast({
  variant: "danger",
  title: "Error",
  description: "Something went wrong. Please try again.",
});

Toast with Action

import { ToastAction } from "@eqtylab/equality";

toast({
  title: "Action Required",
  description: "This toast includes an action button.",
  action: <ToastAction altText="Undo">Undo</ToastAction>,
});

Updating a Toast

const toastInstance = toast({
  description: "Uploading...",
});

// Later, update the toast
toastInstance.update({
  variant: "success",
  description: "Upload complete!",
});

Dismissing a Toast

const toastInstance = toast({
  description: "Processing...",
});

// Dismiss programmatically
toastInstance.dismiss();