useToast

Hooks that manage toast notification state, swipe dismissal, auto-timeout, and stacking behavior.

basic-demo

Usage#

import { toast, useToaster } from '@primereact/headless/toaster';
import { useToast } from '@primereact/headless/toast';
 
const toaster = useToaster({ position: 'bottom-right' });
const { rootProps, regionProps, toasts } = toaster;
 
const { rootProps: toastRootProps, closeProps, state } = useToast({ toast: toastData, toaster });
 
return (
    <div {...rootProps}>
        <div {...regionProps}>
            {toasts.map((t) => (
                <div {...toastRootProps}>
                    <button {...closeProps}></button>
                </div>
            ))}
        </div>
    </div>
);

useToaster manages the toast container state while useToast handles individual toast lifecycle — see Primitive for a component-based API.

Features#

Two-hook architecture: useToaster for container/region state, useToast for per-toast behavior
Global toast function for imperative toast creation with variant methods (success, danger, warn, info, loading, custom, promise)
Returns spread-ready prop objects (rootProps, regionProps, closeProps, actionProps, titleProps, descriptionProps, iconProps)
Built-in swipe-to-dismiss with directional detection (left, right, up, down)
Auto-timeout with pause on hover/interaction and document visibility tracking
Stacked toast layout with expand-on-hover behavior
Toast grouping via the group prop

Behavior#

Creating Toasts#

Use the toast function to create notifications imperatively. It returns a toast ID for later reference.

import { toast } from '@primereact/headless/toaster';
 
const id = toast({
    title: 'Update available',
    description: 'A new version is ready to use.'
});

Variants#

Use variant methods to create typed toasts. Each method sets the appropriate variant value.

toast.success({ title: 'Saved', description: 'Your changes have been saved.' });
toast.danger({ title: 'Error', description: 'Something went wrong.' });
toast.warn({ title: 'Warning', description: 'Check your input.' });
toast.info({ title: 'Info', description: 'New update available.' });
toast.loading({ title: 'Loading...', description: 'Please wait.' });

Custom JSX#

Use toast.custom to render arbitrary JSX as the toast content. The first argument is a ReactElement or a function that receives the toast ID.

toast.custom(<div>Custom content</div>, { duration: 5000 });
 
toast.custom((id) => (
    <div>
        <button onClick={() => toast.dismiss(id)}>Close</button>
    </div>
));

Promise#

Use toast.promise to create a toast that transitions through loading, success, and error states based on a Promise result.

toast.promise(fetchData(), {
    loading: { title: 'Loading...' },
    success: (data) => ({ title: 'Done', description: `Fetched ${data.length} items.` }),
    error: (err) => ({ title: 'Failed', description: err.message })
});

Dismissing Toasts#

Use toast.dismiss to animate a toast out. Pass no argument to dismiss all toasts.

toast.dismiss(id);
toast.dismiss();

Use toast.remove to remove a toast instantly without animation.

toast.remove(id);

Updating Toasts#

Use toast.update to change the properties of an existing toast by its ID.

const id = toast.loading({ title: 'Uploading...' });
 
toast.update(id, { title: 'Complete', variant: 'success' });

Duration#

Pass duration on individual toasts to override the container-level timeout. Set Infinity to keep the toast visible until manually dismissed.

toast({ title: 'Sticky', duration: Infinity });

Grouping#

Use group on both useToaster and the toast call to route toasts to specific containers. Toasts without a group render in containers without a group.

const toaster = useToaster({ group: 'notifications' });
 
toast({ title: 'Alert', group: 'notifications' });

Position#

Set position on useToaster to control toast placement. The regionProps include the corresponding data-position attribute.

const toaster = useToaster({ position: 'top-center' });

Available values: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right.

Limit#

Set limit to control how many toasts are visible simultaneously. Remaining toasts stack behind the visible ones.

const toaster = useToaster({ limit: 5 });

Close Callbacks#

Use onDismiss and onTimeout on individual toast options to react to dismissal or timeout events.

toast({
    title: 'Notification',
    onDismiss: (t) => console.log('dismissed', t.id),
    onTimeout: (t) => console.log('timed out', t.id)
});

Toast State#

useToast exposes state for each toast, reflecting its lifecycle phase. Use these values for conditional styling or rendering.

const { state } = useToast({ toast: toastData, toaster });
 
// state.mounted — true after initial render
// state.removed — true when the toast is exiting
// state.swiping — true during active swipe gesture
// state.swipeOut — true after swipe threshold exceeded
// state.swipeOutDirection — 'left' | 'right' | 'up' | 'down'
// state.isSwiped — true when swipe delta exceeds zero
// state.initialHeight — measured height for stacking calculations
// state.offsetBeforeRemove — captured offset for exit animation

Custom Styling with Data Attributes#

rootProps from both hooks include data attributes for CSS-based styling.

Toaster region:

[data-position='bottom-right'] {
    right: 2rem;
    bottom: 2rem;
}
[data-expanded] {
    /* region is expanded on hover */
}

Individual toast:

[data-variant='success'] {
    border-color: green;
}
[data-mounted] {
    opacity: 1;
}
[data-removed] {
    opacity: 0;
}
[data-front] {
    z-index: 1;
}
[data-swiping] {
    transition: none;
}
[data-swipe-out][data-swipe-direction='left'] {
    transform: translateX(-100%);
}

API#

useToaster#

Name	Type	Default
`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

useToast#

Name	Type	Default
`toast`	`ToastType`	—
Toast data containing all toast information
`toaster`	`ToasterRootInstance`	—
Reference to the parent Toaster instance

Accessibility#

See Toast Primitive for WAI-ARIA compliance details and keyboard support.