Toast

An unstyled, accessible toast notification system with compound composition.

Build fully custom toast notifications with complete control over layout, animation, and styling.

basic-demo

Pre-styled Versions

Choose a pre-styled library to use Toast with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with two component groups: Toaster (Root, Portal, Region) and Toast (Root, Icon, Title, Description, Action, Close)
Global toast function with variant methods (success, danger, warn, info, loading, custom, promise)
Built-in swipe-to-dismiss with directional detection
Stacked toast layout with expand-on-hover
Auto-timeout with pause on hover, interaction, and document visibility

Usage#

import { Toast } from 'primereact/toast';
import { Toaster, toast } from 'primereact/toaster';

<Toaster.Root>
    <Toaster.Portal>
        <Toaster.Region>
            {({ toaster }) =>
                toaster?.toasts?.map((t) => (
                    <Toast.Root key={t.id} toast={t}>
                        <Toast.Icon />
                        <Toast.Title />
                        <Toast.Description />
                        <Toast.Action />
                        <Toast.Close />
                    </Toast.Root>
                ))
            }
        </Toaster.Region>
    </Toaster.Portal>
</Toaster.Root>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element or use a custom React component.

<Toast.Close as="div">...</Toast.Close>
<Toast.Action as={MyButton}>...</Toast.Action>

Default elements: Toaster.Root=div, Toaster.Region=div, Toast.Root=div, Toast.Icon=span, Toast.Title=div, Toast.Description=div, Toast.Action=button, Toast.Close=button.

Render Function Children#

Toaster.Region accepts a render function as children, providing access to the toaster instance for iterating over toasts.

<Toaster.Region>
    {({ toaster }) =>
        toaster?.toasts?.map((t) => (
            <Toast.Root key={t.id} toast={t}>
                ...
            </Toast.Root>
        ))
    }
</Toaster.Region>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

Successfully completed

The task was completed successfully. You can now view the details.

/* Select a part to see its CSS selector for custom styling */

API#

ToasterRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToasterRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToasterRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ToasterRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToasterRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ToasterRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`position`	`ToasterPosition`	`'top-right'`
Position of the toaster container
`limit`	`number`	`3`
Maximum number of toasts to be visible
`gap`	`number`	`14`
Gap between toasts in pixels
`timeout`	`number`	`6000`
Timeout for toast auto-dismiss (alias for duration)
`group`	`string`	—
Group identifier for toast grouping
`richColors`	`boolean`	`false`
Whether to show rich colors
`icons`	`Partial<Record<ToastVariant, ReactNode>>`	`{}`
Custom icons for each toast variant
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-position`	Current position value

ToasterRegion#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToasterRegionInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToasterRegionInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ToasterRegionInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToasterRegionPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ToasterRegionInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-position`	Current position value
`data-expanded`	Present when region is expanded

CSS Custom Properties

The Toaster.Region element sets CSS custom properties on its style for toast layout spacing.

CSS Variable	Description
`--gap`	Vertical gap between toasts in pixels
`--front-toast-height`	Height of the frontmost toast in pixels

ToasterPortal#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToasterPortalInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToasterPortalInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ToasterPortalInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToasterPortalPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ToasterPortalInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

ToastRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToastRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToastRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ToastRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToastRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ToastRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`toast`	`ToastType`	—
Toast data containing all toast information
`toaster`	`ToasterRootInstance`	—
Reference to the parent Toaster instance
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-variant`	Toast variant (`success`, `danger`, etc.)
`data-index`	Toast index in the stack
`data-id`	Toast identifier
`data-mounted`	Present after initial render
`data-removed`	Present during exit animation
`data-visible`	Present when within the visible limit
`data-front`	Present on the frontmost toast
`data-expanded`	Present when toaster is expanded
`data-swiping`	Present during active swipe
`data-swiped`	Present after swipe delta exceeds zero
`data-swipe-out`	Present after swipe threshold exceeded
`data-swipe-direction`	Swipe direction (`left`, `right`, `up`, `down`)
`data-dismissible`	Present when toast is dismissible
`data-rich-colors`	Present when rich colors are enabled

CSS Custom Properties

The Toast.Root element sets CSS custom properties on its style for swipe gestures and stacked positioning.

CSS Variable	Description
`--initial-height`	Initial height of the toast before animation
`--toast-index`	Index of the toast in the stack
`--toast-z-index`	Z-index stacking order for the toast
`--toast-offset`	Vertical offset position in pixels
`--swipe-amount-x`	Horizontal swipe distance in pixels
`--swipe-amount-y`	Vertical swipe distance in pixels

Defines passthrough(pt) options of ToastRoot component.

label	type	description
root	ToastRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
icon	ToastRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the icon's DOM element.
title	ToastRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the title's DOM element.
description	ToastRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the description's DOM element.
action	ToastRootPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the action button's DOM element.
close	ToastRootPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the close button's DOM element.

ToastTitle#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToastTitleInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToastTitleInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ToastTitleInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToastTitlePassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ToastTitleInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-variant`	Toast variant (`success`, `danger`, etc.)

Defines passthrough(pt) options of ToastTitle component.

label	type	description
root	ToastTitlePassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

ToastDescription#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToastDescriptionInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToastDescriptionInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ToastDescriptionInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToastDescriptionPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ToastDescriptionInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-variant`	Toast variant (`success`, `danger`, etc.)

Defines passthrough(pt) options of ToastDescription component.

label	type	description
root	ToastDescriptionPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

ToastIcon#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToastIconInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToastIconInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ToastIconInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToastIconPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ToastIconInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-variant`	Toast variant (`success`, `danger`, etc.)

Defines passthrough(pt) options of ToastIcon component.

label	type	description
root	ToastIconPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

ToastAction#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToastActionInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToastActionInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ToastActionInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToastActionPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ToastActionInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-variant`	Toast variant (`success`, `danger`, etc.)

Defines passthrough(pt) options of ToastAction component.

label	type	description
root	ToastActionPassThroughType<ButtonHTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

ToastClose#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ToastCloseInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ToastCloseInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ToastCloseInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ToastClosePassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ToastCloseInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-variant`	Toast variant (`success`, `danger`, etc.)

Defines passthrough(pt) options of ToastClose component.

label	type	description
root	ToastClosePassThroughType<ButtonHTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

ToastRegion#

ToastItem#

Accessibility#

Toast uses role="alert" which implicitly sets aria-live to assertive and aria-atomic to true, ensuring screen readers announce toast content immediately. The toaster region uses role="region" with tabIndex="0" to allow keyboard navigation to the toast area.

Non-visible toasts are marked with aria-hidden="true" and inert to prevent screen reader interaction.

Keyboard Support#

Key	Function
`tab`	Moves focus into or out of the toast region.
`enter`	Activates the focused toast action or close button.
`space`	Activates the focused toast action or close button.