---
id: toast
title: Toast
description: A message that appears on the screen to provide feedback on an action.
---

<ComponentPreview id="Toast" />

## Anatomy

<Anatomy id="toast" />

```tsx
const toaster = createToaster({ placement: 'bottom-end' })

<Toaster toaster={toaster}>
  {(toast) => (
    <Toast.Root>
      <Toast.Title />
      <Toast.Description />
      <Toast.ActionTrigger />
      <Toast.CloseTrigger />
    </Toast.Root>
  )}
</Toaster>
```

## Setup

To use the Toast component, create the toast engine using the `createToaster` function.

This function manages the placement and grouping of toasts, and provides a `toast` object needed to create toast
notification.

```ts
const toaster = createToaster({
  placement: 'bottom-end',
  overlap: true,
  gap: 24,
})
```

## Examples

Here's an example of creating a toast using the `toast.create` method.

<Example id="basic" />

### Types

You can create different types of toasts (`success`, `error`, `warning`, `info`) with appropriate styling. For example,
to create a success toast, you can do:

```ts
toaster.success({
  title: 'Success!',
  description: 'Your changes have been saved.',
})
```

<Example id="types" />

### Promise

You can use `toaster.promise()` to automatically handle the different states of an asynchronous operation. It provides
options for the `success`, `error`, and `loading` states of the promise and will automatically update the toast when the
promise resolves or rejects.

<Example id="promise-toast" />

### Update

To update a toast, use the `toast.update` method.

<Example id="update" />

### Action

To add an action to a toast, use the `toast.action` property.

<Example id="action" />

### Duration

You can control how long a toast stays visible by setting a custom `duration` in milliseconds, or use `Infinity` to keep
it visible until manually dismissed.

<Example id="duration" />

### Max Visible

Set the `max` prop on the `createToaster` function to define the maximum number of toasts that can be rendered at any
one time. Any extra toasts will be queued and rendered when a toast has been dismissed.

<Example id="max-toasts" />

### Placement

Configure where toasts appear on the screen using the `placement` option in `createToaster`. Options include
`top-start`, `top-end`, `bottom-start`, `bottom-end`, and more.

<Example id="placement" />

## Guides

### Toast in Effects

When creating a toast inside React effects (like `useEffect`, `useLayoutEffect`, or event handlers that trigger during
render), you may encounter a "flushSync" warning. To avoid this, wrap the toast call in `queueMicrotask`:

```tsx
import { useEffect } from 'react'

export const EffectToast = () => {
  useEffect(() => {
    // ❌ This may cause flushSync warnings
    // toaster.create({ title: 'Effect triggered!' })

    // ✅ Wrap in queueMicrotask to avoid warnings
    queueMicrotask(() => {
      toaster.create({
        title: 'Effect triggered!',
        description: 'This toast was called safely from an effect',
        type: 'success',
      })
    })
  }, [])

  return <div>Component content</div>
}
```

This ensures the toast creation is deferred until after the current execution context, preventing React's concurrent
rendering warnings.

### Styling

There's a minimal styling required for the toast to work correctly.

#### Toast root

The toast root will be assigned these css properties at runtime:

- `--x` - The x position
- `--y` - The y position
- `--scale` - The scale
- `--z-index` - The z-index
- `--height` - The height
- `--opacity` - The opacity
- `--gap` - The gap between toasts

```css
[data-scope='toast'][data-part='root'] {
  translate: var(--x) var(--y);
  scale: var(--scale);
  z-index: var(--z-index);
  height: var(--height);
  opacity: var(--opacity);
  will-change: translate, opacity, scale;
  transition:
    translate 400ms,
    scale 400ms,
    opacity 400ms,
    height 400ms,
    box-shadow 200ms;
  transition-timing-function: cubic-bezier(0.21, 1.02, 0.73, 1);

  &[data-state='closed'] {
    transition:
      translate 400ms,
      scale 400ms,
      opacity 200ms;
    transition-timing-function: cubic-bezier(0.06, 0.71, 0.55, 1);
  }
}
```

#### Styling based on type

You can also style based on the `data-type` attribute.

```css
[data-scope='toast'][data-part='root'] {
  &[data-type='error'] {
    background: red;
    color: white;
  }

  &[data-type='info'] {
    background: blue;
    color: white;
  }

  &[data-type='warning'] {
    background: orange;
  }

  &[data-type='success'] {
    background: green;
    color: white;
  }
}
```

#### Mobile considerations

A very common use case is to adjust the toast width on mobile so it spans the full width of the screen.

```css
@media (max-width: 640px) {
  [data-scope='toast'][data-part='group'] {
    width: 100%;
  }

  [data-scope='toast'][data-part='root'] {
    inset-inline: 0;
    width: calc(100% - var(--gap) * 2);
  }
}
```

## API Reference

### Props

<ComponentTypes id="toast" />

### Context

<ContextType id="toast" />
