---
title: "Toast"
description: "Auto-dismissing notification message with variants"
source: "Equality"
---
import { ToastDemo } from "@demo/components/demo/toast";
import { ToastRoot } from "@eqtylab/equality";

<ToastRoot client:only="react" />

## 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

<ToastDemo client:only="react" />

### Danger

<ToastDemo client:only="react" variant="danger" />

### Warning

<ToastDemo client:only="react" variant="warning" />

### Success

<ToastDemo client:only="react" variant="success" />

### With Action

<ToastDemo client:only="react" variant="with-action" />

## Usage

Import the components and hooks:

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

First, add the `ToastRoot` component to your application root:

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

Basic usage with the `useToast` hook:

```tsx
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

```tsx
const { toast } = useToast();

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

### Toast with Title and Variant

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

### Toast with Action

```tsx
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

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

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

### Dismissing a Toast

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

// Dismiss programmatically
toastInstance.dismiss();
```