Toast · base-ui-svelte

Updating toasts

useToastManager().update accepts a partial object or a function of the current toast. Omitted fields are preserved:

const toastManager = Toast.useToastManager();

toastManager.update(id, (prev) => ({
	title: 'Upload complete',
	description: prev.description
}));

API Reference

Props mirror Base UI React where applicable, adapted for Svelte 5. Native HTML attributes for the rendered element are also accepted unless noted.

Toast.Root

Groups all parts of an individual toast. Renders a <div> element.

Props

toast ToastData —

Name: toast
Description: —
Type: ToastData

swipeDirection object ['down', 'right']

Name: swipeDirection
Description: Direction(s) in which the toast can be swiped to dismiss.
Type: ToastSwipeDirection | ToastSwipeDirection[] | undefined
Default: ['down', 'right']

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-closed`	Present when the part is closed.
`data-ending-style`	Present when the toast is animating out.
`data-expanded`	Present when the toast is expanded in the viewport.
`data-limited`	Present when the toast was limited because the toast limit was exceeded.
`data-open`	Present when the part is open.
`data-starting-style`	Present when the toast begins animating in.
`data-swipe-direction`	The direction the toast was swiped.
`data-swiping`	Present when the toast is being swiped.
`data-type`	The type of the toast.

Toast.Provider

Provides a context for creating and managing toasts.

Props

toaster ToastManager —

Name: toaster
Description: —
Type: ToastManager | undefined

timeout number 5000

Name: timeout
Description: The default amount of time (in ms) before a toast is auto dismissed. A value of 0 will prevent the toast from being dismissed automatically.
Type: number | undefined
Default: 5000

limit number 3

Name: limit
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 the data-limited attribute) rather than removed, so they can be hidden or animated out.
Type: number | undefined
Default: 3

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Toast.Action

Performs an action when clicked. Renders a <button> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Toast.Arrow

Displays an element positioned against the toast anchor. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-anchored`	Present on the element when applicable.
`data-side`	Indicates which side the toast is positioned relative to the anchor.

Toast.Close

Closes the toast when clicked. Renders a <button> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Toast.Content

A container for the contents of a toast. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-behind`	Present when the toast is behind the frontmost toast in the stack.
`data-expanded`	Present when the toast viewport is expanded.

Toast.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.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-type`	The type of the toast.

Toast.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.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Toast.Positioner

Positions the toast against the anchor. Renders a <div> element.

Props

side t<HT 'top'

Name: side
Description: Which side of the anchor element to align the toast against. May automatically change to avoid collisions.
Type: t<HT
Default: 'top'

align s<HTM 'center'

Name: align
Description: How to align the popup relative to the specified side.
Type: s<HTM
Default: 'center'

sideOffset hildre 0

Name: sideOffset
Description: Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a data object parameter with the following properties: data.anchor: the dimensions of the anchor element with properties width and height.data.positioner: the dimensions of the positioner element with properties width and height.data.side: which side of the anchor element the positioner is aligned against.data.align: how the positioner is aligned relative to the specified side.
Type: hildre
Default: 0

alignOffset ?: Sni 0

Name: alignOffset
Description: Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a data object parameter with the following properties: data.anchor: the dimensions of the anchor element with properties width and height.data.positioner: the dimensions of the positioner element with properties width and height.data.side: which side of the anchor element the positioner is aligned against.data.align: how the positioner is aligned relative to the specified side.
Type: ?: Sni
Default: 0

collisionPadding ToastSwipeDirection = 'up' | 'down' | 5

Name: collisionPadding
Description: Additional space to maintain from the edge of the collision boundary.
Type: ToastSwipeDirection = 'up' | 'down' |
Default: 5

collisionBoundary rt type ToastRo 'clipping-ancestors'

Name: collisionBoundary
Description: An element or a rectangle that delimits the area that the popup is confined to.
Type: rt type ToastRo
Default: 'clipping-ancestors'

collisionAvoidance butes<HTMLDivEleme —

Name: collisionAvoidance
Description: Determines how to handle collisions when positioning the popup. side controls overflow on the preferred placement axis (top/bottom or left/right): 'flip': keep the requested side when it fits; otherwise try the opposite side
(top and bottom, or left and right).
'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible.
'none': do not correct side-axis overflow. align controls overflow on the alignment axis (start/center/end): 'flip': keep side, but swap start and end when the requested alignment overflows.
'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit.
'none': do not correct alignment-axis overflow. fallbackAxisSide controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: 'start': allow perpendicular fallback and try the logical start side first
(top before bottom, or left before right in LTR).
'end': allow perpendicular fallback and try the logical end side first
(bottom before top, or right before left in LTR).
'none': do not fallback to the perpendicular axis. When side is 'shift', explicitly setting align only supports 'shift' or 'none'.
If align is omitted, it defaults to 'flip'.
Type: butes<HTMLDivEleme

arrowPadding { to 5

Name: arrowPadding
Description: Minimum distance to maintain between the arrow and the edges of the popup. Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
Type: { to
Default: 5

sticky ta; sw false

Name: sticky
Description: Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
Type: ta; sw
Default: false

positionMethod snippet 'absolute'

Name: positionMethod
Description: Maps to Floating UI strategy (absolute | fixed).
Type: ?: Snippet; }; ex
Default: 'absolute'

strategy ppet; }; export t —

Name: strategy
Description: —
Type: ppet; }; export t

anchor snippet —

Name: anchor
Description: Override the positioning anchor (element or virtual element).
Type: ildren?: Snippet; }; export ty

disableAnchorTracking ippet; false

Name: disableAnchorTracking
Description: When true, skip continuous layout tracking of the anchor (position once; no resize/scroll auto-updates beyond the initial compute).
Type: ippet;
Default: false

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-anchored`	Present on the element when applicable.
`data-side`	Indicates which side the toast is positioned relative to the trigger.

Toast.Title

A title that labels the toast. Renders an <h2> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-type`	The type of the toast.

Toast.Viewport

A container viewport for toasts. Renders a <div> element.

Props

children snippet —

Name: children
Description: Content rendered inside the part.
Type: Snippet

Data attributes

Attribute	Description
`data-expanded`	Indicates toasts are expanded in the viewport.