Toast

Generates toast notifications.

'use client';
import * as React from 'react';
import { Toast } from '@base-ui/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.Content className={styles.Content}>
        <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.Content>
    </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/react/toast';

<Toast.Provider>
  <Toast.Portal>
    <Toast.Viewport>
      {/* Stacked toasts */}
      <Toast.Root>
        <Toast.Content>
          <Toast.Title />
          <Toast.Description />
          <Toast.Action />
          <Toast.Close />
        </Toast.Content>
      </Toast.Root>

      {/* Anchored toasts */}
      <Toast.Positioner>
        <Toast.Root>
          <Toast.Arrow />
          <Toast.Content>
            <Toast.Title />
            <Toast.Description />
            <Toast.Action />
            <Toast.Close />
          </Toast.Content>
        </Toast.Root>
      </Toast.Positioner>
    </Toast.Viewport>
  </Toast.Portal>
</Toast.Provider>

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.
The data-base-ui-swipe-ignore attribute can be manually added to elements inside of a toast to prevent swipe-to-dismiss gestures on them. Interactive elements are automatically prevented.

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));
}

<Toast.Content> is used to hide overflow from taller toasts while the stack is collapsed. The data-behind attribute marks content that sits behind the frontmost toast and pairs with the data-expanded attribute so the content fades back in when the viewport expands:

Collapsed content

.ToastContent {
  overflow: hidden;
  transition: opacity 0.25s;
}

.ToastContent[data-behind] {
  opacity: 0;
}

.ToastContent[data-expanded] {
  opacity: 1;
}

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%));
  }
  /* Note: --offset-y is defined locally in these examples and derives from
   --toast-offset-y, --toast-index, and swipe movement values */
  &[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.

The updateKey property increments when a toast is updated or upserted. This can be used to replay attention-grabbing styles by switching animation names or, when remounting is acceptable, by including it in a React key.

Examples

Anchored toasts

Toasts can be anchored to a specific element using <Toast.Positioner> and the positionerProps option when adding a toast. This is useful for showing contextual feedback like transient “Copied” toasts that appear near the button that triggered the action.

Anchored toasts should be rendered in a separate <Toast.Provider> from stacked toasts. A global toast manager can be created for each to manage them separately throughout your app:

Mixing stacked and anchored toasts

const anchoredToastManager = Toast.createToastManager();
const stackedToastManager = Toast.createToastManager();

function App() {
  return (
    <React.Fragment>
      <Toast.Provider toastManager={anchoredToastManager}>
        <AnchoredToasts />
      </Toast.Provider>
      <Toast.Provider toastManager={stackedToastManager}>
        <StackedToasts />
      </Toast.Provider>

      {/* App content */}
    </React.Fragment>
  );
}

function AnchoredToasts() {
  const { toasts } = Toast.useToastManager();
  return (
    <Toast.Portal>
      <Toast.Viewport>
        {toasts.map((toast) => (
          <Toast.Positioner key={toast.id} toast={toast}>
            <Toast.Root toast={toast}>{/* ... */}</Toast.Root>
          </Toast.Positioner>
        ))}
      </Toast.Viewport>
    </Toast.Portal>
  );
}

function StackedToasts() {
  const { toasts } = Toast.useToastManager();
  return (
    <Toast.Portal>
      <Toast.Viewport>
        {toasts.map((toast) => (
          <Toast.Root key={toast.id} toast={toast}>
            {/* ... */}
          </Toast.Root>
        ))}
      </Toast.Viewport>
    </Toast.Portal>
  );
}

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:

Undo action

When adding a toast, the actionProps option can be used to define props for an action button inside of it—this enables the ability to undo an action associated with the toast.

Promise

An asynchronous toast can be created with three possible states: loading, success, and error. The type string matches these states to change the styling. Each of the states also accepts the method options object for more granular control.

Custom

A toast with custom data can be created by passing any typed object interface to the data option. This enables you to pass any data (including functions) you need to the toast and access it in the toast’s rendering logic.

Deduplicated toast

When you upsert the same toast by id, the updateKey property increments so a custom renderer can replay a visual animation. This demo alternates CSS animation names from updateKey, which keeps the same toast mounted while replaying the pulse.

Varying heights

Toasts with varying heights are stacked by ensuring that the <Toast.Content> element has overflow: hidden set, along with all toasts’ heights matching the frontmost toast at index 0. This prevents taller toasts from overflowing the stack when collapsed.

API reference

Provider

Provides a context for creating and managing toasts.

limitnumber3

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 | undefined
Default: 3

toastManagerToastManager—

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

timeoutnumber5000

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 | undefined
Default: 5000

childrenReact.ReactNode—

Name: children
Type: React.ReactNode | undefined

Toast.Provider.PropsHide

Re-Export of Provider props as ToastProviderProps

Toast.Provider.StateHide

type ToastProviderState = {}

Viewport

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

classNamestring | 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 | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toast.Viewport.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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) | undefined

data-expanded

Indicates toasts are expanded in the viewport.

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

--toast-frontmost-height

Indicates the height of the frontmost toast.

CSS Variable	Description	-
`--toast-frontmost-height`	Indicates the height of the frontmost toast.

Toast.Viewport.PropsHide

Re-Export of Viewport props as ToastViewportProps

Toast.Viewport.StateHide

type ToastViewportState = {
  /** Whether toasts are expanded in the viewport. */
  expanded: boolean;
}

Portal

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

containerUnion—

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

classNamestring | 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: any) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | ((state: any) => React.CSSProperties | undefined) | undefined

renderReactElement | 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: any) => ReactElement) | undefined

Toast.Portal.PropsHide

Re-Export of Portal props as ToastPortalProps

Toast.Portal.StateHide

type ToastPortalState = {}

Root

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

swipeDirectionUnion['down', 'right']

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

toast^*

Toast.Root.ToastObject

—

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

classNamestring | 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 | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toast.Root.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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) | undefined

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

Indicates the measured natural height of the toast in pixels.

--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-height`	Indicates the measured natural height of the toast in pixels.
`--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.

Toast.Root.PropsHide

Re-Export of Root props as ToastRootProps

Toast.Root.StateHide

type ToastRootState = {
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the toasts in the viewport are expanded. */
  expanded: boolean;
  /** Whether the toast was removed due to exceeding the limit. */
  limited: boolean;
  /** The type of the toast. */
  type: string | undefined;
  /** Whether the toast is being swiped. */
  swiping: boolean;
  /** The direction the toast is being swiped. */
  swipeDirection: 'up' | 'down' | 'left' | 'right' | undefined;
}

Toast.Root.ToastObjectHide

type ToastRootToastObject<Data extends {} = any> = {
  /** The unique identifier for the toast. */
  id: string;
  /** The ref for the toast. */
  ref?: React.RefObject<HTMLElement | null>;
  /** The title of the toast. */
  title?: React.ReactNode;
  /**
   * The type of the toast. Used to conditionally style the toast,
   * including conditionally rendering elements based on the type.
   */
  type?: string;
  /** The description of the toast. */
  description?: React.ReactNode;
  /**
   * The amount of time (in ms) before the toast is auto dismissed.
   * A value of `0` will prevent the toast from being dismissed automatically.
   * @default 5000
   */
  timeout?: number;
  /**
   * The priority of the toast.
   * - `low` - The toast will be announced politely.
   * - `high` - The toast will be announced urgently.
   * @default 'low'
   */
  priority?: 'low' | 'high';
  /** The transition status of the toast. */
  transitionStatus?: 'starting' | 'ending';
  /** A counter that increments whenever the toast is updated or upserted. */
  updateKey?: number;
  /** Determines if the toast was closed due to the limit being reached. */
  limited?: boolean;
  /** The height of the toast. */
  height?: number;
  /** Callback function to be called when the toast is closed. */
  onClose?: () => void;
  /** Callback function to be called when the toast is removed from the list after any animations are complete when closed. */
  onRemove?: () => void;
  /** The props for the action button. */
  actionProps?: Omit<
    React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>,
    'ref'
  >;
  /** The props forwarded to the toast positioner element when rendering anchored toasts. */
  positionerProps?: ToastManagerPositionerProps;
  /** Custom data for the toast. */
  data?: Data;
}

Content

A container for the contents of a toast. Renders a <div> element.

classNamestring | 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.Content.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toast.Content.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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.Content.State, ) => ReactElement) | undefined

data-behind

Present when the toast is behind the frontmost toast in the stack.

data-expanded

Present when the toast viewport is expanded.

Attribute	Description	-
`data-behind`	Present when the toast is behind the frontmost toast in the stack.
`data-expanded`	Present when the toast viewport is expanded.

Toast.Content.PropsHide

Re-Export of Content props as ToastContentProps

Toast.Content.StateHide

type ToastContentState = {
  /** Whether the toast viewport is expanded. */
  expanded: boolean;
  /** Whether the toast is behind the frontmost toast in the stack. */
  behind: boolean;
}

Title

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

classNamestring | 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 | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toast.Title.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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) | undefined

data-type

The type of the toast.

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

Toast.Title.PropsHide

Re-Export of Title props as ToastTitleProps

Toast.Title.StateHide

type ToastTitleState = {
  /** The type of the toast. */
  type: string | undefined;
}

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.

classNamestring | 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 | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toast.Description.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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) | undefined

data-type

The type of the toast.

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

Toast.Description.PropsHide

Re-Export of Description props as ToastDescriptionProps

Toast.Description.StateHide

type ToastDescriptionState = {
  /** The type of the toast. */
  type: string | undefined;
}

Action

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

nativeButtonbooleantrue

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 (for example, <div>).
Type: boolean | undefined
Default: true

classNamestring | 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 | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toast.Action.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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) | undefined

data-type

The type of the toast.

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

Toast.Action.PropsHide

Re-Export of Action props as ToastActionProps

Toast.Action.StateHide

type ToastActionState = {
  /** The type of the toast. */
  type: string | undefined;
}

Close

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

nativeButtonbooleantrue

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 (for example, <div>).
Type: boolean | undefined
Default: true

classNamestring | 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 | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toast.Close.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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) | undefined

data-type

The type of the toast.

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

Toast.Close.PropsHide

Re-Export of Close props as ToastCloseProps

Toast.Close.StateHide

type ToastCloseState = {
  /** The type of the toast. */
  type: string | undefined;
}

Positioner

Positions the toast against the anchor. Renders a <div> element.

disableAnchorTrackingbooleanfalse

Name: disableAnchorTracking
Description: Whether to disable the popup from tracking any layout shift of its positioning anchor.
Type: boolean | undefined
Default: false

toast^*

ToastObject<any>

—

Name: toast
Description: The toast object associated with the positioner.
Type: ToastObject<any>

alignAlign'center'

Name: align
Description: How to align the popup relative to the specified side.
Type: 'start' | 'center' | 'end' | undefined
Default: 'center'

alignOffsetnumber | OffsetFunction0

Name: alignOffset
Description: Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment.

The function takes a data object parameter with the following properties:

data.anchor: the dimensions of the anchor element with properties width and height.

data.positioner: the dimensions of the positioner element with properties width and height.

data.side: which side of the anchor element the positioner is aligned against.

data.align: how the positioner is aligned relative to the specified side.
Type: | number | ((data: { side: | 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'; align: 'start' | 'center' | 'end'; anchor: { width: number; height: number }; positioner: { width: number; height: number }; }) => number) | undefined
Default: 0
Example: <Positioner alignOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.width : anchor.height; }} />

sideSide'top'

Name: side
Description: Which side of the anchor element to align the toast against. May automatically change to avoid collisions.
Type: | 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | undefined
Default: 'top'

sideOffsetnumber | OffsetFunction0

Name: sideOffset
Description: Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.

The function takes a data object parameter with the following properties:

data.anchor: the dimensions of the anchor element with properties width and height.

data.positioner: the dimensions of the positioner element with properties width and height.

data.side: which side of the anchor element the positioner is aligned against.

data.align: how the positioner is aligned relative to the specified side.
Type: | number | ((data: { side: | 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'; align: 'start' | 'center' | 'end'; anchor: { width: number; height: number }; positioner: { width: number; height: number }; }) => number) | undefined
Default: 0
Example: <Positioner sideOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.height : anchor.width; }} />

arrowPaddingnumber5

Name: arrowPadding
Description: Minimum distance to maintain between the arrow and the edges of the popup.

Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
Type: number | undefined
Default: 5

anchorElement | null—

Name: anchor
Description: An element to position the toast against.
Type: Element | null | undefined

collisionAvoidanceCollisionAvoidance—

Name: collisionAvoidance
Description: Determines how to handle collisions when positioning the popup.

side controls overflow on the preferred placement axis (top/bottom or left/right):

'flip': keep the requested side when it fits; otherwise try the opposite side (top and bottom, or left and right).

'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible.

'none': do not correct side-axis overflow.

align controls overflow on the alignment axis (start/center/end):

'flip': keep side, but swap start and end when the requested alignment overflows.

'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit.

'none': do not correct alignment-axis overflow.

fallbackAxisSide controls fallback behavior on the perpendicular axis when the preferred axis cannot fit:

'start': allow perpendicular fallback and try the logical start side first (top before bottom, or left before right in LTR).

'end': allow perpendicular fallback and try the logical end side first (bottom before top, or right before left in LTR).

'none': do not fallback to the perpendicular axis.

When side is 'shift', explicitly setting align only supports 'shift' or 'none'. If align is omitted, it defaults to 'flip'.
Type: CollisionAvoidance | undefined
Example: <Positioner collisionAvoidance={{ side: 'shift', align: 'shift', fallbackAxisSide: 'none', }} />

collisionBoundaryBoundary'clipping-ancestors'

Name: collisionBoundary
Description: An element or a rectangle that delimits the area that the popup is confined to.
Type: Boundary | undefined
Default: 'clipping-ancestors'

collisionPaddingPadding5

Name: collisionPadding
Description: Additional space to maintain from the edge of the collision boundary.
Type: Padding | undefined
Default: 5

stickybooleanfalse

Name: sticky
Description: Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
Type: boolean | undefined
Default: false

positionMethod'absolute' | 'fixed''absolute'

Name: positionMethod
Description: Determines which CSS position property to use.
Type: 'absolute' | 'fixed' | undefined
Default: 'absolute'

classNamestring | 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.Positioner.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toast.Positioner.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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.Positioner.State, ) => ReactElement) | undefined

data-anchor-hidden

Present when the anchor is hidden.

data-align

Indicates how the toast is aligned relative to specified side.

data-side

Indicates which side the toast is positioned relative to the trigger.

Attribute	Description	-
`data-anchor-hidden`	Present when the anchor is hidden.
`data-align`	Indicates how the toast is aligned relative to specified side.
`data-side`	Indicates which side the toast is positioned relative to the trigger.

--anchor-height

The anchor’s height.

--anchor-width

The anchor’s width.

--available-height

The available height between the anchor and the edge of the viewport.

--available-width

The available width between the anchor and the edge of the viewport.

--transform-origin

The coordinates that this element is anchored to. Used for animations and transitions.

CSS Variable	Description	-
`--anchor-height`	The anchor’s height.
`--anchor-width`	The anchor’s width.
`--available-height`	The available height between the anchor and the edge of the viewport.
`--available-width`	The available width between the anchor and the edge of the viewport.
`--transform-origin`	The coordinates that this element is anchored to. Used for animations and transitions.

Toast.Positioner.PropsHide

Re-Export of Positioner props as ToastPositionerProps

Toast.Positioner.StateHide

type ToastPositionerState = {
  /** The side of the anchor the component is placed on. */
  side: 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';
  /** The alignment of the component relative to the anchor. */
  align: 'start' | 'center' | 'end';
  /** Whether the anchor element is hidden. */
  anchorHidden: boolean;
}

Arrow

Displays an element positioned against the toast anchor. Renders a <div> element.

classNamestring | 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.Arrow.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Toast.Arrow.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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.Arrow.State, ) => ReactElement) | undefined

data-uncentered

Present when the toast arrow is uncentered.

data-align

Indicates how the toast is aligned relative to specified side.

data-side

Indicates which side the toast is positioned relative to the anchor.

Attribute	Description	-
`data-uncentered`	Present when the toast arrow is uncentered.
`data-align`	Indicates how the toast is aligned relative to specified side.
`data-side`	Indicates which side the toast is positioned relative to the anchor.

Toast.Arrow.PropsHide

Re-Export of Arrow props as ToastArrowProps

Toast.Arrow.StateHide

type ToastArrowState = {
  /** The side of the anchor the component is placed on. */
  side: 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';
  /** The alignment of the component relative to the anchor. */
  align: 'start' | 'center' | 'end';
  /** Whether the arrow cannot be centered on the anchor. */
  uncentered: boolean;
}

useToastManager

Manages toasts, called inside of a <Toast.Provider>.

Usage

const toastManager = Toast.useToastManager();

Return value

UseToastManagerReturnValue

toasts

ToastObject<{}>[]

Name: toasts
Type: ToastObject<{}>[]

addfunction

Name: add
Type: <T extends {} = {}>( options: ToastManagerAddOptions<T>, ) => string

closefunction

Name: close
Type: (toastId?: string) => void

updatefunction

Name: update
Type: <T extends {} = {}>( toastId: string, options: ToastManagerUpdateOptions<T>, ) => void

promisefunction

Name: promise
Type: <Value, T extends {} = {}>( promise: Promise<Value>, options: ToastManagerPromiseOptions<Value, T>, ) => Promise<Value>

`add` method

Creates a toast by adding it to the toast list.

If you pass an id that already exists, the existing toast is updated in place instead of creating a duplicate.

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);

Or you can close all toasts at once by not passing an ID:

Close all toasts

toastManager.close();

`promise` method

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

Description configuration

const promise = 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 promise = 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
        },
      },
    },
  },
);

See full promise method

Additional Types

ToastObjectHide

type ToastObject<Data extends {}> = {
  /** The unique identifier for the toast. */
  id: string;
  /** The ref for the toast. */
  ref?: React.RefObject<HTMLElement | null>;
  /** The title of the toast. */
  title?: React.ReactNode;
  /**
   * The type of the toast. Used to conditionally style the toast,
   * including conditionally rendering elements based on the type.
   */
  type?: string;
  /** The description of the toast. */
  description?: React.ReactNode;
  /**
   * The amount of time (in ms) before the toast is auto dismissed.
   * A value of `0` will prevent the toast from being dismissed automatically.
   * @default 5000
   */
  timeout?: number;
  /**
   * The priority of the toast.
   * - `low` - The toast will be announced politely.
   * - `high` - The toast will be announced urgently.
   * @default 'low'
   */
  priority?: 'low' | 'high';
  /** The transition status of the toast. */
  transitionStatus?: 'starting' | 'ending';
  /** A counter that increments whenever the toast is updated or upserted. */
  updateKey?: number;
  /** Determines if the toast was closed due to the limit being reached. */
  limited?: boolean;
  /** The height of the toast. */
  height?: number;
  /** Callback function to be called when the toast is closed. */
  onClose?: () => void;
  /** Callback function to be called when the toast is removed from the list after any animations are complete when closed. */
  onRemove?: () => void;
  /** The props for the action button. */
  actionProps?: Omit<
    React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>,
    'ref'
  >;
  /** The props forwarded to the toast positioner element when rendering anchored toasts. */
  positionerProps?: ToastManagerPositionerProps;
  /** Custom data for the toast. */
  data?: Data;
}

ToastManagerHide

type ToastManager<Data extends {} = any> = {
  ' subscribe': (listener: (data: ToastManagerEvent) => void) => () => void;
  add: <T extends Data = Data>(options: ToastManagerAddOptions<T>) => string;
  close: (id?: string) => void;
  update: <T extends Data = Data>(id: string, updates: ToastManagerUpdateOptions<T>) => void;
  promise: <Value, T extends Data = Data>(
    promiseValue: Promise<Value>,
    options: ToastManagerPromiseOptions<Value, T>,
  ) => Promise<Value>;
}

ToastManagerAddOptionsHide

type ToastManagerAddOptions<Data extends {}> = {
  /**
   * The unique identifier for the toast. Adding a toast with an existing ID
   * updates it in place and refreshes its auto-dismiss timer.
   */
  id?: string;
  /** The title of the toast. */
  title?: React.ReactNode;
  /**
   * The type of the toast. Used to conditionally style the toast,
   * including conditionally rendering elements based on the type.
   */
  type?: string;
  /** The description of the toast. */
  description?: React.ReactNode;
  /**
   * The amount of time (in ms) before the toast is auto dismissed.
   * A value of `0` will prevent the toast from being dismissed automatically.
   * @default 5000
   */
  timeout?: number;
  /**
   * The priority of the toast.
   * - `low` - The toast will be announced politely.
   * - `high` - The toast will be announced urgently.
   * @default 'low'
   */
  priority?: 'low' | 'high';
  /** The transition status of the toast. */
  transitionStatus?: 'starting' | 'ending';
  /** Callback function to be called when the toast is closed. */
  onClose?: () => void;
  /** Callback function to be called when the toast is removed from the list after any animations are complete when closed. */
  onRemove?: () => void;
  /** The props for the action button. */
  actionProps?: Omit<
    React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>,
    'ref'
  >;
  /** The props forwarded to the toast positioner element when rendering anchored toasts. */
  positionerProps?: ToastManagerPositionerProps;
  /** Custom data for the toast. */
  data?: Data;
}

ToastManagerEventHide

type ToastManagerEvent = { action: 'add' | 'close' | 'update' | 'promise'; options: any }

ToastManagerPositionerPropsHide

type ToastManagerPositionerProps = {
  /** An element to position the toast against. */
  anchor?: Element | null;
  /**
   * Style applied to the element, or a function that
   * returns a style object based on the component's state.
   */
  style?:
    | React.CSSProperties
    | ((state: Toast.Positioner.State) => React.CSSProperties | undefined);
  /**
   * CSS class applied to the element, or a function that
   * returns a class based on the component's state.
   */
  className?: string | ((state: Toast.Positioner.State) => string | undefined);
  /**
   * Which side of the anchor element to align the toast against.
   * May automatically change to avoid collisions.
   * @default 'top'
   */
  side?: 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';
  /**
   * Determines which CSS `position` property to use.
   * @default 'absolute'
   */
  positionMethod?: 'absolute' | 'fixed';
  /**
   * Distance between the anchor and the popup in pixels.
   * Also accepts a function that returns the distance to read the dimensions of the anchor
   * and positioner elements, along with its side and alignment.
   *
   * The function takes a `data` object parameter with the following properties:
   * - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.
   * - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.
   * - `data.side`: which side of the anchor element the positioner is aligned against.
   * - `data.align`: how the positioner is aligned relative to the specified side.
   * @default 0
   * @example
   * ```jsx
   * <Positioner
   *   sideOffset={({ side, align, anchor, positioner }) => {
   *     return side === 'top' || side === 'bottom'
   *       ? anchor.height
   *       : anchor.width;
   *   }}
   * />
   * ```
   */
  sideOffset?: number | ((data: {
  side: 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';
  align: 'start' | 'center' | 'end';
  anchor: { width: number; height: number };
  positioner: { width: number; height: number };
}) => number);
  /**
   * How to align the popup relative to the specified side.
   * @default 'center'
   */
  align?: 'start' | 'center' | 'end';
  /**
   * Additional offset along the alignment axis in pixels.
   * Also accepts a function that returns the offset to read the dimensions of the anchor
   * and positioner elements, along with its side and alignment.
   *
   * The function takes a `data` object parameter with the following properties:
   * - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.
   * - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.
   * - `data.side`: which side of the anchor element the positioner is aligned against.
   * - `data.align`: how the positioner is aligned relative to the specified side.
   * @default 0
   * @example
   * ```jsx
   * <Positioner
   *   alignOffset={({ side, align, anchor, positioner }) => {
   *     return side === 'top' || side === 'bottom'
   *       ? anchor.width
   *       : anchor.height;
   *   }}
   * />
   * ```
   */
  alignOffset?: number | ((data: {
  side: 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';
  align: 'start' | 'center' | 'end';
  anchor: { width: number; height: number };
  positioner: { width: number; height: number };
}) => number);
  /**
   * An element or a rectangle that delimits the area that the popup is confined to.
   * @default 'clipping-ancestors'
   */
  collisionBoundary?: Boundary;
  /**
   * Additional space to maintain from the edge of the collision boundary.
   * @default 5
   */
  collisionPadding?: Padding;
  /**
   * Whether to maintain the popup in the viewport after
   * the anchor element was scrolled out of view.
   * @default false
   */
  sticky?: boolean;
  /**
   * Minimum distance to maintain between the arrow and the edges of the popup.
   *
   * Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
   * @default 5
   */
  arrowPadding?: number;
  /**
   * Whether to disable the popup from tracking any layout shift of its positioning anchor.
   * @default false
   */
  disableAnchorTracking?: boolean;
  /**
   * Determines how to handle collisions when positioning the popup.
   *
   * `side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):
   * - `'flip'`: keep the requested side when it fits; otherwise try the opposite side
   *   (`top` and `bottom`, or `left` and `right`).
   * - `'shift'`: never change side; keep the requested side and move the popup within
   *   the clipping boundary so it stays visible.
   * - `'none'`: do not correct side-axis overflow.
   *
   * `align` controls overflow on the alignment axis (`start`/`center`/`end`):
   * - `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.
   * - `'shift'`: keep side and requested alignment, then nudge the popup along the
   *   alignment axis to fit.
   * - `'none'`: do not correct alignment-axis overflow.
   *
   * `fallbackAxisSide` controls fallback behavior on the perpendicular axis when the
   * preferred axis cannot fit:
   * - `'start'`: allow perpendicular fallback and try the logical start side first
   *   (`top` before `bottom`, or `left` before `right` in LTR).
   * - `'end'`: allow perpendicular fallback and try the logical end side first
   *   (`bottom` before `top`, or `right` before `left` in LTR).
   * - `'none'`: do not fallback to the perpendicular axis.
   *
   * When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.
   * If `align` is omitted, it defaults to `'flip'`.
   * @example
   * ```jsx
   * <Positioner
   *   collisionAvoidance={{
   *     side: 'shift',
   *     align: 'shift',
   *     fallbackAxisSide: 'none',
   *   }}
   * />
   * ```
   */
  collisionAvoidance?: CollisionAvoidance;
  /**
   * 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.
   */
  render?: ReactElement | ((props: HTMLProps, state: Toast.Positioner.State) => ReactElement);
}

ToastManagerPromiseOptionsHide

type ToastManagerPromiseOptions<Value, Data extends {}> = {
  loading: string | ToastManagerUpdateOptions<Data>;
  success:
    | string
    | ToastManagerUpdateOptions<Data>
    | ((result: Value) => string | ToastManagerUpdateOptions<Data>);
  error:
    | string
    | ToastManagerUpdateOptions<Data>
    | ((error: any) => string | ToastManagerUpdateOptions<Data>);
}

ToastManagerUpdateOptionsHide

type ToastManagerUpdateOptions<Data extends {}> = {
  /** The title of the toast. */
  title?: React.ReactNode;
  /**
   * The type of the toast. Used to conditionally style the toast,
   * including conditionally rendering elements based on the type.
   */
  type?: string;
  /** The description of the toast. */
  description?: React.ReactNode;
  /**
   * The amount of time (in ms) before the toast is auto dismissed.
   * A value of `0` will prevent the toast from being dismissed automatically.
   * @default 5000
   */
  timeout?: number;
  /**
   * The priority of the toast.
   * - `low` - The toast will be announced politely.
   * - `high` - The toast will be announced urgently.
   * @default 'low'
   */
  priority?: 'low' | 'high';
  /** Callback function to be called when the toast is closed. */
  onClose?: () => void;
  /** Callback function to be called when the toast is removed from the list after any animations are complete when closed. */
  onRemove?: () => void;
  /** The props for the action button. */
  actionProps?: Omit<
    React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>,
    'ref'
  >;
  /** The props forwarded to the toast positioner element when rendering anchored toasts. */
  positionerProps?: ToastManagerPositionerProps;
  /** Custom data for the toast. */
  data?: Data;
}

UseToastManagerReturnValueHide

type UseToastManagerReturnValue<Data extends {} = any> = {
  toasts: ToastObject<Data>[];
  add: <T extends Data = Data>(options: ToastManagerAddOptions<T>) => string;
  close: (toastId?: string) => void;
  update: <T extends Data = Data>(toastId: string, options: ToastManagerUpdateOptions<T>) => void;
  promise: <Value, T extends Data = Data>(
    promise: Promise<Value>,
    options: ToastManagerPromiseOptions<Value, T>,
  ) => Promise<Value>;
}