---
title: Toast
subtitle: Generates toast notifications.
description: A high-quality, unstyled React toast component to generate notifications.
---
# Toast
A high-quality, unstyled React toast component to generate notifications.
## Demo
### Tailwind
This example shows how to implement the component using Tailwind CSS.
```tsx
/* index.tsx */
'use client';
import * as React from 'react';
import { Toast } from '@base-ui/react/toast';
export default function ExampleToast() {
return (
);
}
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 (
);
}
function ToastList() {
const { toasts } = Toast.useToastManager();
return toasts.map((toast) => (
));
}
function XIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
```
### CSS Modules
This example shows how to implement the component using CSS Modules.
```css
/* index.module.css */
.Button {
box-sizing: border-box;
display: flex;
align-items: center;
justify-content: center;
height: 2.5rem;
padding: 0 0.875rem;
margin: 0;
outline: 0;
border: 1px solid var(--color-gray-200);
border-radius: 0.375rem;
background-color: var(--color-gray-50);
font-family: inherit;
font-size: 1rem;
font-weight: 500;
line-height: 1.5rem;
color: var(--color-gray-900);
user-select: none;
@media (hover: hover) {
&:hover {
background-color: var(--color-gray-100);
}
}
&:active {
background-color: var(--color-gray-100);
}
&:focus-visible {
outline: 2px solid var(--color-blue);
outline-offset: -1px;
}
}
.Viewport {
position: fixed;
z-index: 1;
width: 250px;
margin: 0 auto;
bottom: 1rem;
right: 1rem;
left: auto;
top: auto;
@media (min-width: 500px) {
bottom: 2rem;
right: 2rem;
width: 300px;
}
}
.Toast {
--gap: 0.75rem;
--peek: 0.75rem;
--scale: calc(max(0, 1 - (var(--toast-index) * 0.1)));
--shrink: calc(1 - var(--scale));
--height: var(--toast-frontmost-height, var(--toast-height));
--offset-y: calc(
var(--toast-offset-y) * -1 + (var(--toast-index) * var(--gap) * -1) +
var(--toast-swipe-movement-y)
);
position: absolute;
right: 0;
margin: 0 auto;
box-sizing: border-box;
background: var(--color-gray-50);
color: var(--color-gray-900);
border: 1px solid var(--color-gray-200);
padding: 1rem;
width: 100%;
box-shadow: 0 2px 10px rgb(0 0 0 / 0.1);
background-clip: padding-box;
border-radius: 0.5rem;
transform-origin: bottom center;
bottom: 0;
left: auto;
margin-right: 0;
-webkit-user-select: none;
user-select: none;
transition:
transform 0.5s cubic-bezier(0.22, 1, 0.36, 1),
opacity 0.5s,
height 0.15s;
cursor: default;
z-index: calc(1000 - var(--toast-index));
height: var(--height);
transform: translateX(var(--toast-swipe-movement-x))
translateY(
calc(
var(--toast-swipe-movement-y) - (var(--toast-index) * var(--peek)) -
(var(--shrink) * var(--height))
)
)
scale(var(--scale));
&[data-expanded] {
transform: translateX(var(--toast-swipe-movement-x)) translateY(var(--offset-y));
height: var(--toast-height);
}
&[data-starting-style],
&[data-ending-style] {
transform: translateY(150%);
}
&[data-limited] {
opacity: 0;
}
&[data-ending-style] {
opacity: 0;
&[data-swipe-direction='up'] {
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));
}
&[data-swipe-direction='down'] {
transform: translateY(calc(var(--toast-swipe-movement-y) + 150%));
}
}
&::after {
content: '';
position: absolute;
top: 100%;
width: 100%;
left: 0;
height: calc(var(--gap) + 1px);
}
}
.Content {
overflow: hidden;
transition: opacity 0.25s;
&[data-behind] {
opacity: 0;
}
&[data-expanded] {
opacity: 1;
}
}
.Title {
font-weight: 500;
font-size: 0.975rem;
line-height: 1.25rem;
margin: 0;
}
.Description {
font-size: 0.925rem;
line-height: 1.25rem;
margin: 0;
}
.Close {
position: absolute;
top: 0.5rem;
right: 0.5rem;
padding: 0;
border: none;
background: transparent;
width: 1.25rem;
height: 1.25rem;
display: flex;
align-items: center;
justify-content: center;
border-radius: 0.25rem;
&:hover {
background-color: var(--color-gray-100);
}
}
.Icon {
width: 1rem;
height: 1rem;
}
```
```tsx
/* index.tsx */
'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 (
);
}
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 (
);
}
function ToastList() {
const { toasts } = Toast.useToastManager();
return toasts.map((toast) => (
));
}
function XIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
```
## Anatomy
Import the component and assemble its parts:
```jsx title="Anatomy"
import { Toast } from '@base-ui/react/toast';
{/* Stacked toasts */}
{/* Anchored toasts */}
;
```
## General usage
- `` 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-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.
## Global manager
A global toast manager can be created by passing the `toastManager` prop to the ``.
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.
```tsx title="Creating a manager instance"
const toastManager = Toast.createToastManager();
```
```jsx title="Using the instance"
```
## 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.
```css title="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.
```css title="Expanded offset"
.Toast[data-expanded] {
transform: translateY(var(--toast-offset-y));
}
```
`` 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:
```css title="Collapsed content" "data-behind" "data-expanded"
.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.
```css title="Swipe offset" "--toast-swipe-movement-x" "--toast-swipe-movement-y"
.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.
```css title="Swipe direction" "data-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.
## Examples
### Anchored toasts
Toasts can be anchored to a specific element using `` 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 `` from stacked toasts. A global toast manager can be created for each to manage them separately throughout your app:
```tsx title="Mixing stacked and anchored toasts"
const anchoredToastManager = Toast.createToastManager();
const stackedToastManager = Toast.createToastManager();
function App() {
return (
{/* App content */}
);
}
function AnchoredToasts() {
const { toasts } = Toast.useToastManager();
return (
{toasts.map((toast) => (
{/* ... */}
))}
);
}
function StackedToasts() {
const { toasts } = Toast.useToastManager();
return (
{toasts.map((toast) => (
{/* ... */}
))}
);
}
```
## Demo
### Tailwind
This example shows how to implement the component using Tailwind CSS.
```tsx
/* index.tsx */
'use client';
import * as React from 'react';
import { Toast } from '@base-ui/react/toast';
import { Button } from '@base-ui/react/button';
import { Tooltip } from '@base-ui/react/tooltip';
const stackedToastManager = Toast.createToastManager();
const anchoredToastManager = Toast.createToastManager();
export default function ExampleToast() {
return (
` element.
**Viewport Props:**
| Prop | Type | Default | Description |
| :-------- | :---------------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: Toast.Viewport.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component’s state. |
| style | `CSSProperties \| ((state: Toast.Viewport.State) => CSSProperties \| undefined)` | - | - |
| render | `ReactElement \| ((props: HTMLProps, state: Toast.Viewport.State) => ReactElement)` | - | 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. |
**Viewport Data Attributes:**
| Attribute | Type | Description |
| :------------ | :-------- | :--------------------------------------------- |
| data-expanded | `boolean` | Indicates toasts are expanded in the viewport. |
**Viewport CSS Variables:**
| Variable | Type | Default | Description |
| :----------------------- | :------- | :------ | :------------------------------------------- |
| --toast-frontmost-height | `number` | - | Indicates the height of the frontmost toast. |
### Portal
A portal element that moves the viewport to a different part of the DOM.
By default, the portal element is appended to ``.
Renders a `
` element.
**Portal Props:**
| Prop | Type | Default | Description |
| :-------- | :---------------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| container | `HTMLElement \| ShadowRoot \| RefObject \| null` | - | A parent element to render the portal element into. |
| className | `string \| ((state: any) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component’s state. |
| style | `CSSProperties \| ((state: any) => CSSProperties \| undefined)` | - | - |
| render | `ReactElement \| ((props: HTMLProps, state: any) => ReactElement)` | - | 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. |
### Root
Groups all parts of an individual toast.
Renders a `
` element.
**Root Props:**
| Prop | Type | Default | Description |
| :------------- | :------------------------------------------------------------------------------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| swipeDirection | `'up' \| 'down' \| 'left' \| 'right' \| ('left' \| 'right' \| 'up' \| 'down')[]` | `['down', 'right']` | Direction(s) in which the toast can be swiped to dismiss. |
| toast | `Toast.Root.ToastObject` | - | The toast to render. |
| className | `string \| ((state: Toast.Root.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component’s state. |
| style | `CSSProperties \| ((state: Toast.Root.State) => CSSProperties \| undefined)` | - | - |
| render | `ReactElement \| ((props: HTMLProps, state: Toast.Root.State) => ReactElement)` | - | 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. |
**Root Data Attributes:**
| Attribute | Type | Description |
| :------------------- | :------------------------------------ | :------------------------------------------------------------- |
| data-expanded | `boolean` | Present when the toast is expanded in the viewport. |
| data-limited | `boolean` | Present when the toast was removed due to exceeding the limit. |
| data-swipe-direction | `'up' \| 'down' \| 'left' \| 'right'` | The direction the toast was swiped. |
| data-swiping | `boolean` | Present when the toast is being swiped. |
| data-type | `string` | 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. |
**Root CSS Variables:**
| Variable | Type | Default | Description |
| :----------------------- | :------- | :------ | :--------------------------------------------------------------------------- |
| --toast-height | `number` | - | Indicates the measured natural height of the toast in pixels. |
| --toast-index | `number` | - | Indicates the index of the toast in the list. |
| --toast-offset-y | `number` | - | Indicates the vertical pixels offset of the toast in the list when expanded. |
| --toast-swipe-movement-x | `number` | - | Indicates the horizontal swipe movement of the toast. |
| --toast-swipe-movement-y | `number` | - | Indicates the vertical swipe movement of the toast. |
### Content
A container for the contents of a toast.
Renders a `
` element.
**Content Props:**
| Prop | Type | Default | Description |
| :-------- | :--------------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: Toast.Content.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component’s state. |
| style | `CSSProperties \| ((state: Toast.Content.State) => CSSProperties \| undefined)` | - | - |
| render | `ReactElement \| ((props: HTMLProps, state: Toast.Content.State) => ReactElement)` | - | 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. |
**Content Data Attributes:**
| Attribute | Type | Description |
| :------------ | :-------- | :----------------------------------------------------------------- |
| data-behind | `boolean` | Present when the toast is behind the frontmost toast in the stack. |
| data-expanded | `boolean` | Present when the toast viewport is expanded. |
### Title
A title that labels the toast.
Renders an `
` element.
**Title Props:**
| Prop | Type | Default | Description |
| :-------- | :------------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: Toast.Title.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component’s state. |
| style | `CSSProperties \| ((state: Toast.Title.State) => CSSProperties \| undefined)` | - | - |
| render | `ReactElement \| ((props: HTMLProps, state: Toast.Title.State) => ReactElement)` | - | 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. |
**Title Data Attributes:**
| Attribute | Type | Description |
| :-------- | :------- | :--------------------- |
| data-type | `string` | 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 `
` element.
**Description Props:**
| Prop | Type | Default | Description |
| :-------- | :------------------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: Toast.Description.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component’s state. |
| style | `CSSProperties \| ((state: Toast.Description.State) => CSSProperties \| undefined)` | - | - |
| render | `ReactElement \| ((props: HTMLProps, state: Toast.Description.State) => ReactElement)` | - | 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. |
**Description Data Attributes:**
| Attribute | Type | Description |
| :-------- | :------- | :--------------------- |
| data-type | `string` | The type of the toast. |
### Action
Performs an action when clicked.
Renders a `