Alert Stack

4.39 KB gzip3.86 KB brotli4.52 KB zstd

sv-alert-stack displays stackable alerts on the page’s top layer.

Warning

Use a single alert stack per document. Multiple stacks compete over the keyboard shortcut and focus.

Usage

The element renders nothing on its own; alerts are created from script:

<sv-alert-stack></sv-alert-stack>

const alertStack = document.querySelector("sv-alert-stack");

alertStack.create({
  severity: "error",
  title: "File not found",
  description: "The file at /path/to/file does not exist",
});

The stack expands on hover, on tap, and when an alert receives keyboard focus. Auto-dismiss timers pause while it is expanded.

Position and offset

Combine one vertical attribute with one horizontal attribute:

<sv-alert-stack top end></sv-alert-stack>

Offset the stack from the viewport edge by padding the wrapper part:

sv-alert-stack::part(wrapper) {
  padding-block-start: 2rem;
  padding-inline-end: 2rem;
}

Swipe to dismiss

Swiping is enabled on the stack, not per alert:

<sv-alert-stack swipe-dismiss></sv-alert-stack>

The swipeToDismiss option then opts a single alert out of it.

Custom actions and icons

An actionButton.action replaces the default dismissal, so dismiss the alert once the work is done:

const dismiss = alertStack.create({
  title: "Export ready",
  actionButton: {
    label: "Download",
    action: () => {
      downloadFile();
      dismiss();
    },
  },
});

iconOverride replaces the severity icon. Return nothing to keep the default icon for that severity.

The icon renders inside the shadow DOM, so give it a part attribute when it needs external styling:

alertStack.create({
  severity: "success",
  title: "Export ready",
  iconOverride: () => {
    const icon = document.createElement("span");
    icon.part = "icon icon-success";
    icon.textContent = "OK";
    return icon;
  },
});

sv-alert-stack::part(icon-success) {
  color: var(--sv-success);
}

Accessibility

Alerts with severity "error" are announced as role="alert", the rest as role="status". Alerts created before the page finishes loading are not announced.

An appearing alert never takes keyboard focus, so its buttons can be far away in tab order. The shortcut attribute, Alt+T by default, focuses the first alert and expands the stack. Escape collapses the stack and restores the previous focus.

The stack is labelled "Notifications"; set aria-label on the element to rename it.

Give auto-dismissing alerts enough time to be read. Frequent or rapid alerts overwhelm users relying on assistive technologies.

API References

Methods

`create()`

Creates an item and adds it to the stack.
Returns a function that dismisses and removes the item.

export type ItemOptions = {
  // The id of the item.
  id?: string;

  // The severity of the item.
  // Default: "info"
  severity?: Severity;

  // The title of the item.
  // Default: severity.toUpperCase()
  title?: string;

  // The message of the item.
  // Default: ""
  description?: string;

  // The time before auto dismissing the item in milliseconds. Use `-1` to disable auto dismiss.
  // Default: -1
  duration?: number;

  // Whether this item can be dismissed with a swipe gesture.
  // Default: true
  swipeToDismiss?: boolean;

  // Whether to show an action button.
  // Use `null` to remove the action button.
  actionButton?: null | {
    // The text of the action button.
    // Default: "Dismiss"
    label?: string;

    // The click event handler.
    // Default: dismiss the item
    action?: (event: MouseEvent) => void;
  };

  // Optional function to provide a custom icon element.
  //
  // If provided, this function receives the item's `severity` and
  // should return an `HTMLElement` to replace the default severity icon.
  //
  // Allows full customization of the icon, including animated or complex elements.
  iconOverride?: (severity: Severity) => HTMLElement;
};

Type (options?: ItemOptions) => DismissItem

Properties

`maxExpandedItems`

The number of items shown when the stack is expanded.

A hidden item with keyboard focus is temporarily brought to the front, then returned when focus leaves it.

Type numberDefault 3

`maxItems`

The maximum number of items allowed in the stack.

When this limit is exceeded, the oldest item is removed.

Type numberDefault 5

`swipeDismiss`

Whether items can be dismissed by swiping them horizontally.

Type booleanDefault false

`items`

All item elements within the container.

Type HTMLLIElement[]Readonly

`shortcut`

Keyboard shortcut used to focus and expand the stack.

The shortcut is written as a + separated string, such as "Alt+T" or "Alt+Shift+T".

Type string

Attributes

`"top"`

Positions the stack at the top of the page

Type boolean

`"bottom"`

Has no effect because the stack is positioned at the bottom by default

Type boolean

`"start"`

Positions the stack on the start side of the screen (left in LTR, right in RTL)

Type boolean

`"center"`

Positions the stack in the center of the screen

Type boolean

`"end"`

Has no effect because the stack is positioned on the end side by default (right in LTR, left in RTL)

Type boolean

`"max-items"`

The maximum number of items allowed in the stack.

When this limit is exceeded, the oldest item is removed.

Type numberDefault 5

`"max-expanded-items"`

The number of items shown when the stack is expanded.

A hidden item with keyboard focus is temporarily brought to the front, then returned when focus leaves it.

Type numberDefault 3

`"shortcut"`

Keyboard shortcut used to focus and expand the stack.

The shortcut is written as a + separated string, such as "Alt+T" or "Alt+Shift+T".

Type string

`"swipe-dismiss"`

Whether items can be dismissed by swiping them horizontally.

Type boolean

Events

`closed`

Fired when the user dismisses an alert using its action button or a swipe.

Type CustomEvent<HTMLElement>Detail The alert card element that was dismissed.Cancelable

`removed`

Emitted just before an item is removed from the stack.

Type CustomEvent<HTMLElement>Detail The item element that is about to be removed.

`added`

Emitted when an item is added to the stack.

Type CustomEvent<HTMLElement>Detail The item element that was added.

CSS Properties

Name	Description
`--sv-toggle-dur`	The duration of stack animations.
`--sv-toggle-ease`	The easing function used by stack animations.
`--sv-success`	Color for success icons and titles
`--sv-error`	Color for error icons and titles
`--sv-info`	Color for info icons and titles
`--sv-warning`	Color for warning icons and titles
`--sv-gray-6`	The background color of the items.
`--sv-gray-2`	The text color of the items and the dismiss action button.
`--sv-gray-5`	The background color of the dismiss action button.
`--sv-bdr-rad-md`	The border radius of the items.
`--sv-bdr-rad-sm`	The border radius of the dismiss action button.
`--sv-bdr-sz-sm`	The border size of the items.

CSS Parts

Name	Description
`::part(popover)`	The popover element to display the alerts at the top of the page.
`::part(wrapper)`	Cards container element.
`::part(alert)`	The card container element.
`::part(icon)`	The icon svg element.
`::part(title)`	The title element.
`::part(action-button)`	The action button element.
`::part(description)`	The description element.