Toast primitive

Headless Toast: the behavior, keyboard support and ARIA of the WAI-ARIA live region pattern, with no styles.

@ndop/primitives/toast
WAI-ARIA: live region

Import

Primitives ship in the @ndop/primitives package and have no styles. Their state is on data attributes for you to style. The styled Toast is built on this one.

import {
  NdToast,
  NdToastDescription,
  NdToasterOutlet,
  NdToastRegion,
  NdToastTitle,
  NdToastAction,
  NdToastClose,
} from '@ndop/primitives/toast';

Accessibility

Implements the live region pattern of the WAI-ARIA Authoring Practices.

Keyboard

Keys the component handles.

Key	Action
`F8`	Focuses the toast region from anywhere on the page.
`Tab`	Moves through the toasts' buttons, then on to the page.
`Escape`	With focus in a toast, dismisses it.

Focus

Toasts never take focus. F8 moves focus to the region; while it's there, nothing times out.
When a toast with focus inside is dismissed, focus moves to the region.

Right-to-left

Toasts swipe toward the end side, so to the left in right-to-left layouts. Direction comes from the nearest dir attribute.

API reference

NdToast

[ndToast]from @ndop/primitives/toast

One toast, whose value is its record from NdToaster.toasts. It's read whole when announced (aria-atomic). Escape dismisses it while focus is inside; swiping it 50 pixels toward the end side does too. data-index (0 is newest), data-front, --nd-toast-index and --nd-toast-swipe are for styling the stack and the swipe.

Manages aria-atomic.

NdToast binding	Type	Default
`[ndToast]`required The toast's record.	`NdToastRecord`	`—`

Data attribute	Values
`data-type`	—
`data-index`	—
`data-front`	—
`data-swiping`	—

NdToastDescription

[ndToastDescription]from @ndop/primitives/toast

A toast's detail, under its title.

NdToasterOutlet

ng-template[ndToaster]from @ndop/primitives/toast

Renders the template of the app's toast region into a CDK global overlay, above everything else, once the app has hydrated, so the live region exists before the first toast. Put one in the app's shell.

NdToastRegion

[ndToastRegion]role regionfrom @ndop/primitives/toast

The landmark the toasts live in: role="region", a polite live region, so new toasts are announced without moving focus. F8 focuses it from anywhere. While the pointer is over it or focus is inside it, timers pause and it has data-expanded, for the styled layer to spread the stack out.

Manages aria-label, aria-live, aria-relevant.

Data attribute	Values
`data-expanded`	—

NdToastTitle

[ndToastTitle]from @ndop/primitives/toast

A toast's message.

NdToastAction

button[ndToastAction]from @ndop/primitives/toast

The button of a toast's action: it runs the action, then dismisses the toast.

NdToastClose

button[ndToastClose]from @ndop/primitives/toast

The button that dismisses its toast. Name it, such as aria-label="Close".