Toast

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

Anatomy

To set up the toast correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

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.

Example not found

Example not found

Example not found

Example not found

Toast 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.',
})

Example not found

Example not found

Example not found

Example not found

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 not found

Example not found

Example not found

Example not found

Update Toast

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

Example not found

Example not found

Example not found

Example not found

Action

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

Example not found

Example not found

Example not found

Example not found

Custom 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 not found

Example not found

Example not found

Example not found

Maximum Visible Toasts

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 not found

Example not found

Example not found

Example not found

Guides

Creating 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 the toast

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

ActionTrigger

CloseTrigger

Description

Title

Toaster

Context

These are the properties available when using Toast.Context, useToastContext hook or useToast hook.

API