Toast
Generates toast notifications.
Anatomy
Import the component and assemble its parts:
General usage
<Toast.Provider>can be wrapped around your entire app, ensuring all toasts are rendered in the same viewport.- F6 lets users jump into the toast viewport landmark region to navigate toasts with keyboard focus.
- The
data-base-ui-swipe-ignoreattribute can be manually added to elements inside of a toast to prevent swipe-to-dismiss gestures on them. Interactive elements are automatically prevented. Toast.getToastManager()returns thetoaststo render and the methods that change them. It reads the context of the<Toast.Provider>, so call it while a component initializes inside the provider. The demos on this page are single components, so they call it in a{@const}tag inside<Toast.Viewport>instead.
Global manager
A global toast manager can be created by passing the toastManager prop to the <Toast.Provider>.
This enables you to queue a toast from anywhere in the app (such as in functions outside a component) while still using the same toast renderer.
The created toastManager exposes the same add, close, update, and promise methods as Toast.getToastManager(). Unlike Toast.getToastManager(), it does not return the reactive toasts array, since it lives outside the component tree.
Stacking and animations
The --toast-index CSS variable can be used to determine the stacking order of the toasts.
The 0th index toast appears at the front.
The --toast-offset-y CSS variable can be used to determine the vertical offset of the toasts when positioned absolutely with a translation offset — this is usually used with the data-expanded attribute, present when the toast viewport is being hovered or has focus.
While the stack is collapsed, each toast's height can be clamped to the frontmost toast's height using the --toast-frontmost-height CSS variable, and <Toast.Content> is used to hide the content of the toasts behind it.
The data-behind attribute marks content that sits behind the frontmost toast and pairs with the data-expanded attribute so the content fades back in when the viewport expands:
The --toast-swipe-movement-x and --toast-swipe-movement-y CSS variables are used to determine the swipe movement of the toasts in order to add a translation offset.
The data-swipe-direction attribute can be used to determine the swipe direction of the toasts to add a translation offset upon dismissal.
The data-limited attribute indicates that the toast exceeded the limit option.
Limited toasts remain mounted with the HTML inert attribute, so this is useful for hiding them or animating them differently.
The updateKey property increments when a toast is updated or upserted.
This can be used to replay attention-grabbing styles by switching animation names or, when remounting is acceptable, by including it in a {#key} block.
Examples
Anchored toasts
Toasts can be anchored to a specific element using <Toast.Positioner> and the positionerProps option when adding a toast. This is useful for showing contextual feedback like transient "Copied" toasts that appear near the button that triggered the action.
Anchored toasts should be rendered in a separate <Toast.Provider> from stacked toasts. A global toast manager can be created for each to manage them separately throughout your app:
Custom position
The position of the toasts is controlled by your own CSS.
To change the toasts' position, you can modify the Toast.Viewport and Toast.Root classes.
A more general component could accept a data-position attribute, which the CSS handles for each variation.
The following shows a top-center position:
Undo action
When adding a toast, the actionProps option can be used to define props for an action button inside of it—this enables the ability to undo an action associated with the toast.
Promise
An asynchronous toast can be created with three possible states: loading, success, and error.
The type string matches these states to change the styling.
Each of the states also accepts the method options object for more granular control.
Custom
A toast with custom data can be created by passing any typed object interface to the data option.
This enables you to pass any data (including functions) you need to the toast and access it in the toast's rendering logic.
Deduplicated toast
When you upsert the same toast by id, the updateKey property increments so a custom renderer can replay a visual animation. This demo alternates CSS animation names from updateKey, which keeps the same toast mounted while replaying the pulse.
Varying heights
Toasts with varying heights are stacked by clamping every toast's height to the frontmost toast at index 0 using the --toast-frontmost-height CSS variable, while the data-behind attribute hides the content of the toasts behind it.
Avoid sizing <Toast.Content> to the root's height (such as height: 100%), as resizing it alongside the root cancels the root's height transition.
API reference
Provider
Provides a context for creating and managing toasts. Renders no element.
timeout number 5000
- Name
- Description
The default amount of time (in ms) before a toast is auto dismissed. A value of
0will prevent the toast from being dismissed automatically.- Type
number- Default
5000
limit number 3
- Name
- Description
The maximum number of toasts that can be displayed at once. When the limit is exceeded, the oldest toasts are marked as
limited(via thedata-limitedattribute) rather than removed, so they can be hidden or animated out.- Type
number- Default
3
toastManager ToastManager —
- Name
- Description
A global manager for toasts to use outside of a component.
- Type
ToastManager
Portal
A portal element that moves the viewport to a different part of the DOM. By default, the portal element is appended to <body>. Renders a <div> element.
container HTMLElement | ShadowRoot | null —
- Name
- Description
Element the portal is appended to.
undefineduses the parent portal ordocument.body.nullwaits and does not mount until an element or shadow root is set. There is no ref object.- Type
HTMLElement | ShadowRoot | null
render Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: ToastPortalState, children: Snippet | undefined]> —
- Name
- Description
Replace the portal element. The snippet receives host props, an empty state, and the children snippet. Host props include the move attachment.
- Type
Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: ToastPortalState, children: Snippet | undefined]>
Viewport
A container viewport for toasts. Renders a <div> element.
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: ToastViewportState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: ToastViewportState, children: Snippet | undefined]>
expanded boolean
- Name
expanded- Description
Whether toasts are expanded in the viewport.
- Type
boolean
data-expanded
--toast-frontmost-height
Root
Groups all parts of an individual toast. Renders a <div> element.
toast* ToastObject —
- Name
- Description
The toast to render.
- Type
ToastObject
swipeDirection ToastSwipeDirection | ToastSwipeDirection[] ['down', 'right']
- Name
- Description
Direction(s) in which the toast can be swiped to dismiss.
- Type
ToastSwipeDirection | ToastSwipeDirection[]- Default
['down', 'right']
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: ToastRootState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: ToastRootState, children: Snippet | undefined]>
transitionStatus 'starting' | 'ending' | undefined
- Name
transitionStatus- Description
The transition status of the component.
- Type
'starting' | 'ending' | undefined
expanded boolean
- Name
expanded- Description
Whether the toasts in the viewport are expanded.
- Type
boolean
limited boolean
- Name
limited- Description
Whether the toast was limited because the toast limit was exceeded.
- Type
boolean
type string | undefined
- Name
type- Description
The type of the toast.
- Type
string | undefined
swiping boolean
- Name
swiping- Description
Whether the toast is being swiped.
- Type
boolean
swipeDirection ToastSwipeDirection | undefined
- Name
swipeDirection- Description
The direction the toast is being swiped.
- Type
ToastSwipeDirection | undefined
data-expanded
data-limited
data-swipe-direction
data-swiping
data-type
data-starting-style
data-ending-style
--toast-height
--toast-index
--toast-offset-y
--toast-swipe-movement-x
--toast-swipe-movement-y
Content
A container for the contents of a toast. Renders a <div> element.
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: ToastContentState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: ToastContentState, children: Snippet | undefined]>
expanded boolean
- Name
expanded- Description
Whether the toast viewport is expanded.
- Type
boolean
behind boolean
- Name
behind- Description
Whether the toast is behind the frontmost toast in the stack.
- Type
boolean
data-behind
data-expanded
Title
A title that labels the toast. Renders an <h2> element.
children Snippet —
- Name
- Description
Content. Falls back to the toast's
title.- Type
Snippet
render Snippet<[props: HTMLAttributes<HTMLHeadingElement>, state: ToastTitleState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLAttributes<HTMLHeadingElement>, state: ToastTitleState, children: Snippet | undefined]>
type string | undefined
- Name
type- Description
The type of the toast.
- Type
string | undefined
data-type
Description
A description that describes the toast. Can be used as the default message for the toast when no title is provided. Renders a <p> element.
children Snippet —
- Name
- Description
Content. Falls back to the toast's
description.- Type
Snippet
render Snippet<[props: HTMLAttributes<HTMLParagraphElement>, state: ToastDescriptionState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLAttributes<HTMLParagraphElement>, state: ToastDescriptionState, children: Snippet | undefined]>
type string | undefined
- Name
type- Description
The type of the toast.
- Type
string | undefined
data-type
Action
Performs an action when clicked. Renders a <button> element.
disabled boolean | null —
- Name
- Type
boolean | null
nativeButton boolean true
- Name
- Description
Whether the host is a native
<button>. Setfalsewhenrendersupplies a non-button element.- Type
boolean- Default
true
children Snippet —
- Name
- Description
Content. The toast's
actionProps.childrenwins over it.- Type
Snippet
render Snippet<[props: HTMLButtonAttributes, state: ToastActionState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLButtonAttributes, state: ToastActionState, children: Snippet | undefined]>
type string | undefined
- Name
type- Description
The type of the toast.
- Type
string | undefined
data-type
Close
Closes the toast when clicked. Renders a <button> element.
disabled boolean | null —
- Name
- Type
boolean | null
nativeButton boolean true
- Name
- Description
Whether the host is a native
<button>. Setfalsewhenrendersupplies a non-button element.- Type
boolean- Default
true
render Snippet<[props: HTMLButtonAttributes, state: ToastCloseState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLButtonAttributes, state: ToastCloseState, children: Snippet | undefined]>
type string | undefined
- Name
type- Description
The type of the toast.
- Type
string | undefined
data-type
Positioner
Positions the toast against the anchor. Renders a <div> element.
toast* ToastObject —
- Name
- Description
The toast object associated with the positioner.
- Type
ToastObject
anchor Element | null —
- Name
- Description
An element to position the toast against. Defaults to the toast's
positionerProps.anchor.- Type
Element | null
positionMethod "absolute" | "fixed" 'absolute'
- Name
- Description
Determines which CSS
positionproperty to use.- Type
"absolute" | "fixed"- Default
'absolute'
side Side 'top'
- Name
- Description
Which side of the anchor element to align the toast against. May automatically change to avoid collisions.
- Type
Side- Default
'top'
align Align 'center'
- Name
- Description
How to align the toast relative to the specified side.
- Type
Align- Default
'center'
sideOffset number | OffsetFunction 0
- Name
- Description
Distance between the anchor and the toast in pixels, or a function of the anchor and positioner dimensions, side, and alignment.
- Type
number | OffsetFunction- Default
0
alignOffset number | OffsetFunction 0
- Name
- Description
Additional offset along the alignment axis in pixels, or a function of the anchor and positioner dimensions, side, and alignment.
- Type
number | OffsetFunction- Default
0
collisionBoundary Boundary 'clipping-ancestors'
- Name
- Description
An element or a rectangle that delimits the area that the toast is confined to.
- Type
Boundary- Default
'clipping-ancestors'
collisionPadding Padding 5
- Name
- Description
Additional space to maintain from the edge of the collision boundary.
- Type
Padding- Default
5
arrowPadding number 5
- Name
- Description
Minimum distance to maintain between the arrow and the edges of the toast.
- Type
number- Default
5
sticky boolean false
- Name
- Description
Whether to maintain the toast in the viewport after the anchor element was scrolled out of view.
- Type
boolean- Default
false
disableAnchorTracking boolean false
- Description
Whether to disable the toast from tracking any layout shift of its positioning anchor.
- Type
boolean- Default
false
collisionAvoidance CollisionAvoidance { fallbackAxisSide: 'end' }
- Name
- Description
Determines how to handle collisions when positioning the toast.
- Type
CollisionAvoidance- Default
{ fallbackAxisSide: 'end' }
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: ToastPositionerState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: ToastPositionerState, children: Snippet | undefined]>
side Side
- Name
side- Description
The side of the anchor the component is placed on.
- Type
Side
align Align
- Name
align- Description
The alignment of the component relative to the anchor.
- Type
Align
anchorHidden boolean
- Name
anchorHidden- Description
Whether the anchor element is hidden.
- Type
boolean
data-anchor-hidden
data-align
data-side
--anchor-height
--anchor-width
--available-height
--available-width
--transform-origin
Arrow
Displays an element positioned against the toast anchor. Renders a <div> element.
render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: ToastArrowState, children: Snippet | undefined]> —
- Name
- Type
Snippet<[props: HTMLAttributes<HTMLDivElement>, state: ToastArrowState, children: Snippet | undefined]>
side Side
- Name
side- Description
The side of the anchor the component is placed on.
- Type
Side
align Align
- Name
align- Description
The alignment of the component relative to the anchor.
- Type
Align
uncentered boolean
- Name
uncentered- Description
Whether the arrow cannot be centered on the anchor.
- Type
boolean
data-uncentered
data-align
data-side
getToastManager
Manages toasts, called inside of a <Toast.Provider>.
Read toasts from the returned object each time you need the list. Destructuring it copies the array once and stops it updating.
| Property | Type | Description |
|---|---|---|
toasts | ToastObject[] | The array of toasts. A read-only getter. |
add | (options: ToastManagerAddOptions) => string | Creates a toast and returns its id. |
close | (toastId?: string) => void | Closes a toast, or every toast when no id is passed. |
update | (toastId: string, options: ToastManagerUpdate) => void | Updates a toast with new options. |
promise | (promise: Promise<Value>, options: ToastManagerPromiseOptions<Value>) => Promise<Value> | Creates an asynchronous toast with loading, success, and error states. |
add method
Creates a toast by adding it to the toast list.
If you pass an id that already exists, the existing toast is updated in place instead of creating a duplicate.
Returns a toastId that can be used to update or close the toast later.
For high priority toasts, the title and description strings are what are used to announce the toast to screen readers.
Screen readers do not announce any extra content rendered inside <Toast.Root>, including the <Toast.Title> or <Toast.Description> components, unless they intentionally navigate to the toast viewport.
update method
Updates the toast with new options.
Options replace the corresponding values of the toast, including custom data, which is replaced as a whole. To derive the update from the current state of the toast, pass a function instead. It receives the current toast and returns the options to apply. Custom data is undefined when the toast has none yet:
close method
Closes the toast, removing it from the toast list after any animations complete.
Or you can close all toasts at once by not passing an ID:
promise method
Creates an asynchronous toast with three possible states: loading, success, and error.
Each state also accepts the method options object to granularly control the toast for each state:
See full promise method