Toast

Generates toast notifications.

'use client';
import * as React from 'react';
import { Toast } from '@base-ui-components/react/toast';
import styles from './index.module.css';

export default function ExampleToast() {
  return (
    <Toast.Provider>
      <ToastButton />
      <Toast.Portal>
        <Toast.Viewport className={styles.Viewport}>
          <ToastList />
        </Toast.Viewport>
      </Toast.Portal>
    </Toast.Provider>
  );
}

function ToastButton() {
  const toastManager = Toast.useToastManager();
  const [count, setCount] = React.useState(0);

  function createToast() {
    setCount((prev) => prev + 1);
    toastManager.add({
      title: `Toast ${count + 1} created`,
      description: 'This is a toast notification.',
    });
  }

  return (
    <button type="button" className={styles.Button} onClick={createToast}>
      Create toast
    </button>
  );
}

function ToastList() {
  const { toasts } = Toast.useToastManager();
  return toasts.map((toast) => (
    <Toast.Root key={toast.id} toast={toast} className={styles.Toast}>
      <Toast.Title className={styles.Title} />
      <Toast.Description className={styles.Description} />
      <Toast.Close className={styles.Close} aria-label="Close">
        <XIcon className={styles.Icon} />
      </Toast.Close>
    </Toast.Root>
  ));
}

function XIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width="24"
      height="24"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      strokeWidth="2"
      strokeLinecap="round"
      strokeLinejoin="round"
      {...props}
    >
      <path d="M18 6 6 18" />
      <path d="m6 6 12 12" />
    </svg>
  );
}

Anatomy

Import the component and assemble its parts:

Anatomy

import { Toast } from '@base-ui-components/react/toast';

<Toast.Provider>
  <Toast.Portal>
    <Toast.Viewport>
      <Toast.Root>
        <Toast.Title />
        <Toast.Description />
        <Toast.Action />
        <Toast.Close />
      </Toast.Root>
    </Toast.Viewport>
  </Toast.Portal>
</Toast.Provider>

API reference

Provider

Provides a context for creating and managing toasts.

limit

number

(default:

3

)

Name: limit
Description: The maximum number of toasts that can be displayed at once. When the limit is reached, the oldest toast will be removed to make room for the new one.
Type: number
Default: 3

toastManager

createToastManager.ToastManager

Name: toastManager
Description: A global manager for toasts to use outside of a React component.
Type: createToastManager.ToastManager

timeout

number

(default:

5000

)

Name: timeout
Description: The default amount of time (in ms) before a toast is auto dismissed. A value of 0 will prevent the toast from being dismissed automatically.
Type: number
Default: 5000

children

ReactNode

Name: children
Type: ReactNode

Viewport

A container viewport for toasts. Renders a <div> element.

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Toast.Viewport.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | ((props: HTMLProps, state: Toast.Viewport.State) => ReactElement)

data-expanded

Indicates toasts are expanded in the viewport.

Attribute	Description
`data-expanded`	Indicates toasts are expanded in the viewport.

Portal

A portal element that moves the viewport to a different part of the DOM. By default, the portal element is appended to <body>.

container

Union

Name: container
Description: A parent element to render the portal element into.
Type: | HTMLElement | RefObject<HTMLElement | null> | null

children

ReactNode

Name: children
Type: ReactNode

Root

Groups all parts of an individual toast. Renders a <div> element.

swipeDirection

Union

(default:

['down', 'right']

)

Name: swipeDirection
Description: Direction(s) in which the toast can be swiped to dismiss.
Type: | 'right' | 'left' | 'up' | 'down' | ('right' | 'left' | 'up' | 'down')[]
Default: ['down', 'right']

toast^*

Toast.Root.ToastObject<any>

Name: toast
Description: The toast to render.
Type: Toast.Root.ToastObject<any>

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Toast.Root.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | ((props: HTMLProps, state: Toast.Root.State) => ReactElement)

data-expanded

Present when the toast is expanded in the viewport.

data-limited

Present when the toast was removed due to exceeding the limit.

data-swipe-direction

The direction the toast was swiped.

data-swiping

Present when the toast is being swiped.

data-type

The type of the toast.

data-starting-style

Present when the toast is animating in.

data-ending-style

Present when the toast is animating out.

Attribute	Description
`data-expanded`	Present when the toast is expanded in the viewport.
`data-limited`	Present when the toast was removed due to exceeding the limit.
`data-swipe-direction`	The direction the toast was swiped.
`data-swiping`	Present when the toast is being swiped.
`data-type`	The type of the toast.
`data-starting-style`	Present when the toast is animating in.
`data-ending-style`	Present when the toast is animating out.

--toast-index

Indicates the index of the toast in the list.

--toast-offset-y

Indicates the vertical pixels offset of the toast in the list when expanded.

--toast-swipe-movement-x

Indicates the horizontal swipe movement of the toast.

--toast-swipe-movement-y

Indicates the vertical swipe movement of the toast.

CSS Variable	Description
`--toast-index`	Indicates the index of the toast in the list.
`--toast-offset-y`	Indicates the vertical pixels offset of the toast in the list when expanded.
`--toast-swipe-movement-x`	Indicates the horizontal swipe movement of the toast.
`--toast-swipe-movement-y`	Indicates the vertical swipe movement of the toast.

Title

A title that labels the toast. Renders an <h2> element.

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Toast.Title.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | ((props: HTMLProps, state: Toast.Title.State) => ReactElement)

data-type

The type of the toast.

Attribute	Description
`data-type`	The type of the toast.

Description

A description that describes the toast. Can be used as the default message for the toast when no title is provided. Renders a <p> element.

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Toast.Description.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | ((props: HTMLProps, state: Toast.Description.State) => ReactElement)

data-type

The type of the toast.

Attribute	Description
`data-type`	The type of the toast.

Action

Performs an action when clicked. Renders a <button> element.

nativeButton

boolean

(default:

true

)

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).
Type: boolean
Default: true

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Toast.Action.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | ((props: HTMLProps, state: Toast.Action.State) => ReactElement)

data-type

The type of the toast.

Attribute	Description
`data-type`	The type of the toast.

Close

Closes the toast when clicked. Renders a <button> element.

nativeButton

boolean

(default:

true

)

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).
Type: boolean
Default: true

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Toast.Close.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | ((props: HTMLProps, state: Toast.Close.State) => ReactElement)

data-type

The type of the toast.

Attribute	Description
`data-type`	The type of the toast.

useToastManager

Manages toasts, called inside of a Toast.Provider.

Usage

const toastManager = Toast.useToastManager();

Return value

toasts

Toast.Root.ToastObject[]

Name: toasts
Description: The array of toast objects.
Type: Toast.Root.ToastObject[]

add

(options: useToast.AddOptions) => string

Name: add
Description: Add a toast to the toast list.
Type: (options: useToast.AddOptions) => string

close

(toastId: string) => void

Name: close
Description: Closes and removes a toast from the toast list.
Type: (toastId: string) => void

update

(toastId: string, options: useToast.UpdateOptions) => void

Name: update
Description: Update a toast in the toast list.
Type: (toastId: string, options: useToast.UpdateOptions) => void

promise

<Value>(promise: Promise<Value>, options: useToast.PromiseOptions) => Promise<Value>

Name: promise
Description: Create a toast that resolves with a value, with three possible states for the toast: loading, success, and error.
Type: <Value>(promise: Promise<Value>, options: useToast.PromiseOptions) => Promise<Value>

Method options

title

string

Name: title
Description: The title of the toast.
Type: string

description

string

Name: description
Description: The description of the toast.
Type: string

type

string

Name: type
Description: The type of the toast. Used to conditionally style the toast or render different elements.
Type: string

timeout

number

Name: timeout
Description: The amount of time (in ms) before the toast is auto dismissed.
Type: number

priority

'low' | 'high'

(default:

'low'

)

Name: priority
Description: The priority of the toast.

low - The toast will be announced politely.

high - The toast will be announced urgently.
Type: 'low' | 'high'
Default: 'low'

onClose

function

Name: onClose
Description: A callback invoked when the toast is closed.
Type: () => void

onRemove

function

Name: onRemove
Description: A callback invoked when the toast is removed from the list after animations complete when closed.
Type: () => void

actionProps

React.ComponentPropsWithRef<'button'>

Name: actionProps
Description: The props of the action button.
Type: React.ComponentPropsWithRef<'button'>

data

Record<string, unknown>

Name: data
Description: The data of the toast.
Type: Record<string, unknown>

`add` method

Creates a toast by adding it to the toast list.

Returns a toastId that can be used to update or close the toast later.

Usage

const toastId = toastManager.add({
  description: 'Hello, world!',
});

Example

function App() {
  const toastManager = Toast.useToastManager();
  return (
    <button
      type="button"
      onClick={() => {
        toastManager.add({
          description: 'Hello, world!',
        });
      }}
    >
      Add toast
    </button>
  );
}

For high priority toasts, the title and description strings are what are used to announce the toast to screen readers. Screen readers do not announce any extra content rendered inside Toast.Root, including the Toast.Title or Toast.Description components, unless they intentionally navigate to the toast viewport.

`update` method

Updates the toast with new options.

Usage

toastManager.update(toastId, {
  description: 'New description',
});

`close` method

Closes the toast, removing it from the toast list after any animations complete.

Usage

toastManager.close(toastId);

`promise` method

Creates an asynchronous toast with three possible states: loading, success, and error.

Description configuration

const toastId = toastManager.promise(
  new Promise((resolve) => {
    setTimeout(() => resolve('world!'), 1000);
  }),
  {
    // Each are a shortcut for the `description` option
    loading: 'Loading...',
    success: (data) => `Hello ${data}`,
    error: (err) => `Error: ${err}`,
  },
);

Each state also accepts the method options object to granularly control the toast for each state:

Method options configuration

const toastId = toastManager.promise(
  new Promise((resolve) => {
    setTimeout(() => resolve('world!'), 1000);
  }),
  {
    loading: {
      title: 'Loading...',
      description: 'The promise is loading.',
    },
    success: {
      title: 'Success',
      description: 'The promise resolved successfully.',
    },
    error: {
      title: 'Error',
      description: 'The promise rejected.',
      actionProps: {
        children: 'Contact support',
        onClick() {
          // Redirect to support page
        },
      },
    },
  },
);

General usage

<Toast.Provider> can be wrapped around your entire app, ensuring all toasts are rendered in the same viewport.
F6 lets users jump into the toast viewport landmark region to navigate toasts with keyboard focus.

Global manager

A global toast manager can be created by passing the toastManager prop to the Toast.Provider. This enables you to queue a toast from anywhere in the app (such as in functions outside the React tree) while still using the same toast renderer.

The created toastManager object has the same properties and methods as the Toast.useToastManager() hook.

Creating a manager instance

const toastManager = Toast.createToastManager();

Using the instance

<Toast.Provider toastManager={toastManager}>

Stacking and animations

The --toast-index CSS variable can be used to determine the stacking order of the toasts. The 0th index toast appears at the front.

z-index stacking

.Toast {
  z-index: calc(1000 - var(--toast-index));
  transform: scale(1 - calc(0.1 * var(--toast-index)));
}

The --toast-offset-y CSS variable can be used to determine the vertical offset of the toasts when positioned absolutely with a translation offset — this is usually used with the data-expanded attribute, present when the toast viewport is being hovered or has focus.

Expanded offset

.Toast[data-expanded] {
  transform: translateY(var(--toast-offset-y));
}

The --toast-swipe-movement-x and --toast-swipe-movement-y CSS variables are used to determine the swipe movement of the toasts in order to add a translation offset.

Swipe offset

.Toast {
  transform: scale(1 - calc(0.1 * var(--toast-index))) + translateX(var(--toast-swipe-movement-x)) +
    translateY(calc(var(--toast-swipe-movement-y) + (var(--toast-index) * -20%)));
}

The data-swipe-direction attribute can be used to determine the swipe direction of the toasts to add a translation offset upon dismissal.

Swipe direction

&[data-ending-style] {
  opacity: 0;

  &[data-swipe-direction='up'] {
    transform: translateY(calc(var(--toast-swipe-movement-y) - 150%));
  }
  &[data-swipe-direction='down'] {
    transform: translateY(calc(var(--toast-swipe-movement-y) + 150%));
  }
  &[data-swipe-direction='left'] {
    transform: translateX(calc(var(--toast-swipe-movement-x) - 150%)) translateY(var(--offset-y));
  }
  &[data-swipe-direction='right'] {
    transform: translateX(calc(var(--toast-swipe-movement-x) + 150%)) translateY(var(--offset-y));
  }
}

The data-limited attribute indicates that the toast was removed from the list due to exceeding the limit option. This is useful for animating the toast differently when it is removed from the list.

Examples

Custom position

The position of the toasts is controlled by your own CSS. To change the toasts’ position, you can modify the Viewport and Root styles. A more general component could accept a data-position attribute, which the CSS handles for each variation. The following shows a top-center position: