Stable in React

Toast

Generates toast notifications.

Loading React 19.3.1…

Hover a part or use it. The code follows. · Loading React…

672Tests passing in React · 0 failing

32.0 KiBSize

Not measured yetMemory

Not measured yetSpeed

productdevbook and 21 upstream authors8 commits · last Nov 4

Install#

One package per framework. Toast's parts come from it; the anatomy tab at the top shows how they nest.

bun add @▢▢▢▢/react

11 parts. The example uses 8 of them; the data does not say which are required.

Toast.ProviderProvides a context for creating and managing toasts.
Toast.PortalA portal element that moves the viewport to a different part of the DOM.
Toast.ViewportA container viewport for toasts.
Toast.RootGroups all parts of an individual toast.
Toast.ContentA container for the contents of a toast.
Toast.TitleA title that labels the toast.
Toast.DescriptionA description that describes the toast.
Toast.CloseCloses the toast when clicked.
Toast.ActionPerforms an action when clicked. Not in the example.
Toast.ArrowDisplays an element positioned against the toast anchor. Not in the example.
Toast.PositionerPositions the toast against the anchor. Not in the example.

Examples#

Common ways to put it to work. Each one runs live.

Positioner and Arrow place a toast next to the button that made it, in its own Provider.

ToastAnchored.tsx

Styling and accessibility#

The parts ship no styles. Style their states with these attributes; the CSS tab at the top has a sheet. The same CSS works in all five frameworks.

[data-expanded]Indicates toasts are expanded in the viewport. On Viewport, Root, Content.
--toast-frontmost-heightIndicates the height of the frontmost toast. On Viewport.
[data-limited]Present when the toast was limited because the toast limit was exceeded. On Root.
[data-type]The type of the toast. On Root, Title, Description, Close, Action.
[data-swiping]Present when the toast is being swiped. On Root.
[data-swipe-direction]The direction the toast was swiped. On Root.
[data-starting-style]Present when the toast begins animating in. On Root.
[data-ending-style]Present when the toast is animating out. On Root.
--toast-indexIndicates the index of the toast in the list. On Root.
--toast-offset-yIndicates the vertical pixels offset of the toast in the list when expanded. On Root.
--toast-heightIndicates the measured natural height of the toast in pixels. On Root.
--toast-swipe-movement-xIndicates the horizontal swipe movement of the toast. On Root.
--toast-swipe-movement-yIndicates the vertical swipe movement of the toast. On Root.
[data-behind]Present when the toast is behind the frontmost toast in the stack. On Content.
[data-side]Indicates which side the toast is positioned relative to the anchor. On Arrow, Positioner.
[data-align]Indicates how the toast is aligned relative to specified side. On Arrow, Positioner.
[data-uncentered]Present when the toast arrow is uncentered. On Arrow.
[data-anchor-hidden]Present when the anchor is hidden. On Positioner.
--available-widthThe available width between the anchor and the edge of the viewport. On Positioner.
--available-heightThe available height between the anchor and the edge of the viewport. On Positioner.
--anchor-widthThe anchor's width. On Positioner.
--anchor-heightThe anchor's height. On Positioner.
--transform-originThe coordinates that this element is anchored to. Used for animations and transitions. On Positioner.

Keyboard

F6Moves focus to the viewport On Viewport.
TabFrom the focused viewport, moves to the first toast On Viewport.
ShiftTabFrom the first toast, returns focus to where it was before On Viewport.
F6From inside the viewport, returns focus to where it was before On Viewport.
EscapeCloses the focused toast On Root.

Set for you

role="region", aria-label="Notifications"screen reader users can find the toasts as a landmarkViewport
aria-live="polite", aria-relevant="additions text", aria-atomic="false"a new toast is read when the reader is idle, without rereading the othersViewport
a visually hidden role="alert" copy of each high-priority toast while focus is outsideurgent toasts are announced at onceViewport
role="dialog" (role="alertdialog" for a high-priority toast), aria-modal="false"a focused toast is read as a small dialog that does not block the pageRoot
aria-labelledby to Title, aria-describedby to Descriptionthe toast is announced with its heading and messageRoot
aria-hidden while the stack is collapsed and not focusedhidden close buttons are not readClose
aria-hidden="true"the decorative arrow is not readArrow

API reference#

22 props across 11 parts, in React syntax, and className, style, render once for every part. Open a row to try it.

Filter props

Toast · all parts

Shared propsEvery part that renders an element takes these.

classNameCSS class applied to the element, or a function that returns a class based on the component's state.string | ((state: State) => string | undefined)

styleStyle applied to the element, or a function that returns a style object based on the component's state.React.CSSProperties | ((state: State) => React.CSSProperties | undefined)

renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State>

Use it in React#

What differs from the React API. Switch the framework at the top of the page.

@▢▢▢▢/react is the React 19 package. Its parts, props, data attributes and error messages are upstream Base UI's, and upstream's own tests run against it.

Parts
Each component is its own entry point and exports one namespace named after it.
```
import { Switch } from '@base-ui-next/react/switch'

export function Example() {
  return (
    <Switch.Root>
      <Switch.Thumb />
    </Switch.Root>
  )
}
```
A part renders the element its API reference names, such as a <span> for Switch.Root.
Props and events
Props and callbacks have upstream's names and signatures: onCheckedChange(checked, details), onOpenChange(open, details), onValueChange(value, details). details carries reason, event, cancel() and allowPropagation(). Native handlers are React's (onClick, onKeyDown), and event.preventBaseUIHandler() stops a part's own handler.
Styling
className takes a string or a function (state) => string; style takes an object or a function (state) => object. The state's data-* attributes are on the element for CSS.
render
render takes an element (render={<a href="/docs" />}) or a function (props, state) => element that spreads props on what it returns.
Refs
ref reaches the part's element. Imperative handles are ref props, as upstream: inputRef, and actionsRef ({ validate } on Field and Form, { unmount, close } on Dialog).
Binding
A part is controlled when its value prop (checked, open, value) is set, and uncontrolled with the default form (defaultChecked, defaultOpen, defaultValue). React has no two-way binding: pair the value with its change callback.
From @base-ui/react
Change the import from @base-ui/react/<component> to @▢▢▢▢/react/<component>.
From @base-ui/react
Nothing else changes: props, parts, data attributes and errors are the same.