beta

useToastState

Provides state management for a toast queue. Toasts display brief, temporary notifications of actions, errors, or other events in an application.

install	`yarn add @react-stately/toast`
version	3.0.0-beta.1
usage	`import {useToastState} from '@react-stately/toast'`

View repository

GitHub

View package

NPM

API#

useToastState<T>(
  (props: ToastStateProps
)): ToastState<T>

Interface#

Properties

Name	Type	Description
`visibleToasts`	`QueuedToast<T>[]`	The visible toasts.

Methods

Method	Description
`add( (content: T, , options?: ToastOptions )): string`	Adds a new toast to the queue.
`close( (key: string )): void`	Closes a toast. If `hasExitAnimation` is true, the toast transitions to an "exiting" state instead of being removed immediately.
`remove( (key: string )): void`	Removes a toast from the visible toasts after an exiting animation.
`pauseAll(): void`	Pauses the timers for all visible toasts.
`resumeAll(): void`	Resumes the timers for all visible toasts.

ToastQueue#

useToastState uses a ToastQueue under the hood, which means the queue is owned by the component that calls it. If you want to have a global toast queue outside the React tree, you can use the ToastQueue class directly. The useToastQueue hook can be used to to subscribe to a ToastQueue within a React component, and returns the same interface as described above.

Properties

Name	Type	Description
`visibleToasts`	`QueuedToast<T>[]`	The currently visible toasts.

Methods

Method	Description
`constructor( (options?: ToastStateProps )): void`
`subscribe( (fn: () => void )): void`	Subscribes to updates to the visible toasts.
`add( (content: T, , options: ToastOptions )): void`	Adds a new toast to the queue.
`close( (key: string )): void`	Closes a toast. If `hasExitAnimation` is true, the toast transitions to an "exiting" state instead of being removed immediately.
`remove( (key: string )): void`	Removes a toast from the visible toasts after an exiting animation.
`pauseAll(): void`	Pauses the timers for all visible toasts.
`resumeAll(): void`	Resumes the timers for all visible toasts.

Example#

See the docs for useToast in react-aria for an example of useToastState.

Name	Type	Description
`maxVisibleToasts`	`number`	The maximum number of toasts to display at a time.
`hasExitAnimation`	`boolean`	Whether toasts have an exit animation. If true, toasts are not removed immediately but transition into an "exiting" state instead. Once the animation is complete, call the `remove` function.

Properties

Name	Type	Description
`visibleToasts`	`QueuedToast<T>[]`	The visible toasts.

Methods

Method	Description
`add( (content: T, , options?: ToastOptions )): string`	Adds a new toast to the queue.
`close( (key: string )): void`	Closes a toast. If `hasExitAnimation` is true, the toast transitions to an "exiting" state instead of being removed immediately.
`remove( (key: string )): void`	Removes a toast from the visible toasts after an exiting animation.
`pauseAll(): void`	Pauses the timers for all visible toasts.
`resumeAll(): void`	Resumes the timers for all visible toasts.

Name	Type	Description
`onClose`	`() => void`	Handler that is called when the toast is closed, either by the user or after a timeout.
`timeout`	`number`	A timeout to automatically close the toast after, in milliseconds.
`priority`	`number`	The priority of the toast relative to other toasts. Larger numbers indicate higher priority.

Name	Type	Description
`content`	`T`	The content of the toast.
`key`	`string`	A unique key for the toast.
`timer`	`Timer`	A timer for the toast, if a timeout was set.
`animation`	`'entering' \| 'queued' \| 'exiting'`	The current animation state for the toast.
`onClose`	`() => void`	Handler that is called when the toast is closed, either by the user or after a timeout.
`timeout`	`number`	A timeout to automatically close the toast after, in milliseconds.
`priority`	`number`	The priority of the toast relative to other toasts. Larger numbers indicate higher priority.

Method	Description
`constructor( (callback: () => void, , delay: number )): void`
`reset( (delay: number )): void`
`pause(): void`
`resume(): void`

Subscribes to a provided toast queue and provides methods to update it.

useToastQueue<T>(
  (queue: ToastQueue<T>
)): ToastState<T>

A ToastQueue is a priority queue of toasts.

Properties

Name	Type	Description
`visibleToasts`	`QueuedToast<T>[]`	The currently visible toasts.

Methods

Method	Description
`constructor( (options?: ToastStateProps )): void`
`subscribe( (fn: () => void )): void`	Subscribes to updates to the visible toasts.
`add( (content: T, , options: ToastOptions )): void`	Adds a new toast to the queue.
`close( (key: string )): void`	Closes a toast. If `hasExitAnimation` is true, the toast transitions to an "exiting" state instead of being removed immediately.
`remove( (key: string )): void`	Removes a toast from the visible toasts after an exiting animation.
`pauseAll(): void`	Pauses the timers for all visible toasts.
`resumeAll(): void`	Resumes the timers for all visible toasts.