Toast imperative API example
Create an imperative API for toast duplication: import * as React from 'react'; import { Toast as ToastPrimitive } from 'radix-ui'; export const Toast = React.forwardRef((props, forwardedRef) => { const { children, ...toastProps } = props; const [count, setCount] = React.useState(0); React.useImperativeHandle(forwardedRef, () => ({ publish: () => setCount((count) => count + 1), })); return (<>{Array.from({ length: count }).map((_, index) => (<ToastPrimitive.Root key={index} {...toastProps}><ToastPrimitive.Description>{children}</ToastPrimitive.Description><ToastPrimitive.Close>Dismiss</ToastPrimitive.Close></ToastPrimitive.Root>))}</> ); });
Toast component parts
A Toast component in Radix consists of Toast.Provider, Toast.Root, Toast.Title, Toast.Description, Toast.Action, Toast.Close, and Toast.Viewport. The Provider wraps the application and manages toast state. Root is the toast container that auto-closes. Title is optional. Description contains the message. Action and Close are optional interactive elements. Viewport is the fixed area where toasts appear.
Toast.Provider props
Toast.Provider has the following props: duration (number, default 5000) - milliseconds before auto-closing each toast; label (string, required, default 'Notification') - localized label for screen readers; swipeDirection (enum: 'right' | 'left' | 'up' | 'down', default 'right') - pointer swipe direction to close; swipeThreshold (number, default 50) - pixels swipe must travel to trigger close; announcerContainer (Element | DocumentFragment, default document.body) - optional container for toast announcements when using focus traps or modals.
Toast.Viewport props
Toast.Viewport has the following props: asChild (boolean, default false) - change rendered element and merge props/behavior; hotkey (string array, default ['F8']) - keyboard shortcut to move focus to viewport, using event.code values from keycode.info or meta key names (ctrlKey, shiftKey, altKey, metaKey); label (string, default 'Notifications ({hotkey})') - localized label for toast region landmarks, with {hotkey} placeholder replaced automatically.
Toast.Root props
Toast.Root has the following props: asChild (boolean, default false) - change rendered element and merge props/behavior; type (enum: 'foreground' | 'background', default 'foreground') - controls sensitivity for accessibility, 'foreground' for user actions announces immediately, 'background' for background tasks announces at next graceful opportunity; duration (number) - milliseconds before closing, overrides provider value; defaultOpen (boolean, default true) - initial open state when uncontrolled; open (boolean) - controlled open state, must be used with onOpenChange; onOpenChange (function: (open: boolean) => void) - called when open state changes; onEscapeKeyDown (function: (event: KeyboardEvent) => void) - called on escape key, preventable; onPause (function: () => void) - called when dismiss timer pauses from pointer hover, focus, or window blur; onResume (function: () => void) - called when dismiss timer resumes from pointer leaving, viewport blur, or window focus; onSwipeStart (function: (event: SwipeEvent) => void) - called at swipe start, preventable; onSwipeMove (function: (event: SwipeEvent) => void) - called during swipe, preventable; onSwipeEnd (function: (event: SwipeEvent) => void) - called at swipe end, preventable; onSwipeCancel (function: (event: SwipeEvent) => void) - called when swipe cancelled, preventable; forceMount (boolean) - force mounting for animation control.
Toast.Root data attributes
Toast.Root exposes the following data attributes: [data-state] with values 'open' or 'closed'; [data-swipe] with values 'start', 'move', 'cancel', or 'end'; [data-swipe-direction] with values 'up', 'down', 'left', or 'right'.
Toast.Root CSS variables for swipe animations
Toast.Root exposes the following CSS variables for swipe gesture animations: --radix-toast-swipe-move-x (offset position when horizontally swiping); --radix-toast-swipe-move-y (offset position when vertically swiping); --radix-toast-swipe-end-x (offset end position after horizontal swipe); --radix-toast-swipe-end-y (offset end position after vertical swipe).
Toast.Title props
Toast.Title has the following props: asChild (boolean, default false) - change rendered element and merge props/behavior.
Toast.Description props
Toast.Description has the following props: asChild (boolean, default false) - change rendered element and merge props/behavior.
Toast.Action props
Toast.Action has the following props: asChild (boolean, default false) - change rendered element and merge props/behavior; altText (string, required) - describes an alternative way to achieve the action for screen reader users who cannot access the toast easily. An action must be safe to ignore to ensure users are not expected to complete tasks with unexpected side effects as a result of a time limit. When obtaining a user response is necessary, portal an AlertDialog styled as a toast into the viewport instead.
Toast.Close props
Toast.Close has the following props: asChild (boolean, default false) - change rendered element and merge props/behavior. It is a button that allows users to dismiss the toast before its duration has elapsed.
Toast behavior on pause and resume
Toast automatically pauses its dismiss timer when the pointer moves over the viewport, the viewport is focused, or when the window is blurred. The timer resumes when the pointer moves away from the viewport, the viewport is blurred, or when the window is focused.
Toast swipe gesture support
Toast supports closing via swipe gesture with a configurable direction (right, left, up, down) and threshold in pixels. The gesture exposes CSS variables for animation control via the data-swipe attribute state.
Toast customizing duration example
To customize the duration of a toast to override the provider value, use the duration prop on Toast.Root: <Toast.Root duration={3000}><Toast.Description>Saved!</Toast.Description></Toast.Root>
Toast custom hotkey example
To override the default hotkey using event.code values from keycode.info: <Toast.Provider>{/* ... */}<Toast.Viewport hotkey={['altKey', 'KeyT']} /></Toast.Provider>
Toast duplicate toasts example
To render multiple toast instances when a user clicks a button, use state to track a count: export default () => { const [savedCount, setSavedCount] = React.useState(0); return (<div><form onSubmit={() => setSavedCount((count) => count + 1)}>{/* ... */}<button>save</button></form>{Array.from({ length: savedCount }).map((_, index) => (<Toast.Root key={index}><Toast.Description>Saved!</Toast.Description></Toast.Root>))}</div>); };
Toast swipe animation CSS example
To animate a swipe-to-close gesture using CSS variables and data-swipe attributes: .ToastRoot[data-swipe='move'] { transform: translateX(var(--radix-toast-swipe-move-x)); } .ToastRoot[data-swipe='cancel'] { transform: translateX(0); transition: transform 200ms ease-out; } .ToastRoot[data-swipe='end'] { animation: slideRight 100ms ease-out; } @keyframes slideRight { from { transform: translateX(var(--radix-toast-swipe-end-x)); } to { transform: translateX(100%); } }
Toast foreground vs background example
Foreground toasts are announced immediately and should result from user actions: <Toast.Root type='foreground'><Toast.Description>File removed successfully.</Toast.Description><Toast.Close>Dismiss</Toast.Close></Toast.Root>. Background toasts are announced at the next graceful opportunity and suit background tasks: <Toast.Root type='background'><Toast.Description>We've just released Radix 1.0.</Toast.Description><Toast.Close>Dismiss</Toast.Close></Toast.Root>
Toast alternative action example
Use the altText prop on Toast.Action to describe an alternative way to action the toast for screen reader users: <Toast.Root type='background'><Toast.Title>Upgrade Available!</Toast.Title><Toast.Description>We've just released Radix 1.0.</Toast.Description><Toast.Action altText='Goto account settings to upgrade'>Upgrade</Toast.Action><Toast.Close>Dismiss</Toast.Close></Toast.Root>
Toast close icon button accessibility example
When providing an icon for Toast.Close, label it correctly for screen reader users: <Toast.Root type='foreground'><Toast.Description>Saved!</Toast.Description><Toast.Close aria-label='Close'><span aria-hidden>×</span></Toast.Close></Toast.Root>
Toast abstract parts custom API example
Create a custom Toast API by abstracting primitive parts: import { Toast as ToastPrimitive } from 'radix-ui'; export const Toast = ({ title, content, children, ...props }) => { return (<ToastPrimitive.Root {...props}>{title && <ToastPrimitive.Title>{title}</ToastPrimitive.Title>}<ToastPrimitive.Description>{content}</ToastPrimitive.Description>{children && (<ToastPrimitive.Action asChild>{children}</ToastPrimitive.Action>)}<ToastPrimitive.Close aria-label='Close'><span aria-hidden>×</span></ToastPrimitive.Close></ToastPrimitive.Root>); };
Toast default order changed
The default toast order changed; toasts now render top to bottom from oldest to newest.
Toast.Root onPause and onResume props
Toast.Root has onPause and onResume props.