Toast

Overview

Toast displays a brief, temporary notification to the user. It’s typically used to provide feedback about an operation or to communicate important information.

Features

Automatically closes after a configurable timeout
Supports closing via pointer, focus, or programmatically
Supports swipe gestures to dismiss
Exposes CSS variables for flexible animations
Manages focus within and across toasts
Respects prefers-reduced-motion

Installation

npm install @radix-ui/react-toast

Anatomy

import * as Toast from '@radix-ui/react-toast';

export default () => (
  <Toast.Provider>
    <Toast.Root>
      <Toast.Title />
      <Toast.Description />
      <Toast.Action />
      <Toast.Close />
    </Toast.Root>

    <Toast.Viewport />
  </Toast.Provider>
)

API Reference

Provider

The provider that wraps your toasts and viewport. It usually wraps the application.

string

default:"'Notification'"

An author-localized label for each toast. Used to help screen reader users associate the interruption with a toast.

number

default:"5000"

Time in milliseconds that each toast should remain visible for.

'right' | 'left' | 'up' | 'down'

default:"'right'"

Direction of pointer swipe that should close the toast.

number

default:"50"

Distance in pixels that the swipe must pass before a close is triggered.

Viewport

The fixed area where toasts appear. Users can jump to the viewport by pressing a hotkey.

string[]

default:"['F8']"

The keys to use as the keyboard shortcut that will move focus to the toast viewport.

string

default:"'Notifications ({hotkey})'"

An author-localized label for the toast viewport to provide context for screen reader users.

Root

The toast that automatically closes. It should not be held open to acquire a user response.

'foreground' | 'background'

default:"'foreground'"

Control the sensitivity of the toast for accessibility purposes. For toasts that are the result of a user action, use foreground. Toasts generated from background tasks should use background.

number

Time in milliseconds that toast should remain visible for. Overrides value from provider.

boolean

The controlled open state of the toast.

boolean

The open state of the toast when it is initially rendered. Use when you do not need to control its open state.

(open: boolean) => void

Event handler called when the open state changes.

(event: KeyboardEvent) => void

Event handler called when the escape key is pressed.

() => void

Event handler called when the dismiss timer is paused.

() => void

Event handler called when the dismiss timer is resumed.

(event: SwipeEvent) => void

Event handler called when starting a swipe interaction.

(event: SwipeEvent) => void

Event handler called during a swipe interaction.

(event: SwipeEvent) => void

Event handler called at the end of a swipe interaction.

boolean

Used to force mounting when more control is needed.

Title

An optional title for the toast.

Description

The toast message.

Action

An action that is safe to ignore to ensure users are not expected to complete tasks with unexpected side effects as a result of a time limit.

string

required

A short description for screen readers announcing the action.

Close

A button that closes the toast.

Examples

Basic Usage

import * as Toast from '@radix-ui/react-toast';
import { useState } from 'react';

export default () => {
  const [open, setOpen] = useState(false);

  return (
    <Toast.Provider swipeDirection="right">
      <button onClick={() => setOpen(true)}>Add to calendar</button>

      <Toast.Root open={open} onOpenChange={setOpen}>
        <Toast.Title>Scheduled: Catch up</Toast.Title>
        <Toast.Description>Friday, February 10, 2023 at 5:30 PM</Toast.Description>
        <Toast.Action altText="Goto schedule to undo">Undo</Toast.Action>
        <Toast.Close aria-label="Close">
          <span aria-hidden>×</span>
        </Toast.Close>
      </Toast.Root>

      <Toast.Viewport />
    </Toast.Provider>
  );
};

Multiple Toasts

import * as Toast from '@radix-ui/react-toast';
import { useState } from 'react';

export default () => {
  const [toasts, setToasts] = useState([]);

  const addToast = () => {
    setToasts((prev) => [
      ...prev,
      { id: Date.now(), title: 'New notification', description: 'You have a new message' },
    ]);
  };

  const removeToast = (id) => {
    setToasts((prev) => prev.filter((toast) => toast.id !== id));
  };

  return (
    <Toast.Provider>
      <button onClick={addToast}>Show toast</button>

      {toasts.map((toast) => (
        <Toast.Root key={toast.id} onOpenChange={(open) => !open && removeToast(toast.id)}>
          <Toast.Title>{toast.title}</Toast.Title>
          <Toast.Description>{toast.description}</Toast.Description>
          <Toast.Close>Close</Toast.Close>
        </Toast.Root>
      ))}

      <Toast.Viewport />
    </Toast.Provider>
  );
};

Data Attributes

Root

data-state - "open" or "closed"
data-swipe - "start", "move", "cancel", or "end"
data-swipe-direction - "up", "down", "left", or "right"

CSS Variables

Root

--radix-toast-swipe-move-x - The offset during a swipe (horizontal)
--radix-toast-swipe-move-y - The offset during a swipe (vertical)
--radix-toast-swipe-end-x - The final offset of a swipe (horizontal)
--radix-toast-swipe-end-y - The final offset of a swipe (vertical)

Keyboard Interactions

F8 - Focuses the toast viewport (configurable via hotkey prop)
Tab - Moves focus to the next focusable element
Shift + Tab - Moves focus to the previous focusable element
Space - When focus is on an action or close button, closes the toast
Enter - When focus is on an action or close button, closes the toast
Escape - Closes the toast

Overlays

Navigation

Forms

Layout

Data Display

Utilities

Overview

Features

Installation

Anatomy

API Reference

Provider

Viewport

Root

Title

Description

Action

Close

Examples

Basic Usage

Multiple Toasts

Data Attributes

Root

CSS Variables

Root

Keyboard Interactions

​Overview

​Features

​Installation

​Anatomy

​API Reference

​Provider

​Viewport

​Root

​Title

​Description

​Action

​Close

​Examples

​Basic Usage

​Multiple Toasts

​Data Attributes

​Root

​CSS Variables

​Root

​Keyboard Interactions

Overview

Features

Installation

Anatomy

API Reference

Provider

Viewport

Root

Title

Description

Action

Close

Examples

Basic Usage

Multiple Toasts

Data Attributes

Root

CSS Variables

Root

Keyboard Interactions