Toast

A message that appears on the screen to provide feedback on an action.

Anatomy

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.

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

Examples

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

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:

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

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.

Update

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

Action

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

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.

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.

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.

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:

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

[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.

[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.

@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

Root

Renders a <div> element.

ActionTrigger

Renders a <button> element.

CloseTrigger

Renders a <button> element.

Description

Renders a <div> element.

Title

Renders a <div> element.

Toaster

Context

API