@spectrum-web-components/alert-banner

Overview

The <sp-alert-banner> displays pressing and high-signal messages, such as system alerts. It is intended to be noticeable and prompt users to take action.

Usage

yarn add @spectrum-web-components/alert-banner

Import the side effectful registration of <sp-alert-banner> via:

import '@spectrum-web-components/alert-banner/sp-alert-banner.js';

Anatomy

The alert dialog consists of several key parts:

Content

The message in its default slot.

<sp-alert-banner open>
    All documents in this folder have been archived
</sp-alert-banner>

Action

An optional action using slot="action":

<sp-alert-banner open>
    Your trial has expired
    <sp-button treatment="outline" variant="secondary" slot="action">
        Buy now
    </sp-button>
</sp-alert-banner>
<bd></bd>

Options

Dismissable

Use the dismissible attribute to include an icon-only close button used to dismiss the alert banner:

<sp-alert-banner open dismissible>
    All documents in this folder have been archived
</sp-alert-banner>

Variants

The <sp-alert-banner> supports three variants, neutral(default), info and negative, to convey the nature of the message:

Info

Use variant="info" for informational messages.

<sp-alert-banner open variant="info" dismissible>
    Your trial will expire in 3 days
    <sp-button treatment="outline" static-color="white" slot="action">
        Buy now
    </sp-button>
</sp-alert-banner>

Negative

Use variant="negative" for error or warning messages.

<sp-alert-banner open variant="negative" dismissible>
    Connection interrupted. Check your network to continue
</sp-alert-banner>

Behaviors

Alert banners should be used for system-level messages and they should be dismissed only as a result of a user action or if the internal state that triggered the alert has been resolved.

The alert can be dismissed by triggering the close button in case of a dismissible alert. It also exposes a public close method to allow consumers to close the alert programmatically.

The component dispatches a close event to announce that the alert banner has been closed. This can be prevented by using the event.preventDefault() API.

Accessibility

The <sp-alert-banner> is rendered with a role of alert to notify screen readers.

When rendering an alert that is dismissable or has actions on a page, ensure the alert is placed in a container with a role of region that includes a unique aria-label or aria-labelledby for better accessibility.

It supports keyboard interactions, including:

Key Action Tab Navigate to the next interactive element Shift + Tab Navigate to the previous interactive element Space/Enter Trigger the focused button Esc Dismiss a dismissible alert ArrowLeft/ArrowRight/ArrowUp/ArrowDown Once focus is on the alert banner, arrow keys can be used to navigate between the close button and the slotted action buttons

Changelog

1.7.0 (2025-06-11)

Minor Changes

sp-overlay: Fixed : Overlays (like pickers and action menus) were incorrectly closing when scrolling occurred within components. The fix ensures the handleScroll method in OverlayStack only responds to document/body scrolling events and ignores component-level scrolling events, which was the original intention.

sp-card: Fixed: On mobile Chrome (both Android and iOS), scrolling on sp-card components would inadvertently trigger click events. This was caused by the timing-based click detection (200ms threshold) in the pointer event handling, which could misinterpret quick scrolls as clicks. This issue did not affect Safari on mobile devices.

sp-action-button: - Fixed : Action buttons with href attributes now properly detects modifier keys and skips the proxy click, allowing only native browser behavior to proceed.

Patch Changes

sp-styles: Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.

sp-card: - Fixed: sp-card component relies on sp-popover for certain toggle interactive behaviors, but this dependency was missing from its dependency tree.

sp-menu: Fixes: Icons in menu stories weren't properly responding to theme changes when used in functional story components. Switching to class-based LitElement components ensures proper component lifecycle hooks and shadow DOM context for icon initialization and theme integration.

sp-tabs: Added @spectrum-web-components/action-button as a dependency for Tabs as its used in the direction button.

sp-split-view: Added @spectrum-web-components/shared dependency in splitview since it uses ranDomId from the shared package

sp-textfield: Replace deprecated word-break: break-word with overflow-wrap: break-word to align with modern CSS standards and improve cross-browser compatibility. This property was deprecated in Chrome 44 (July 2015) in favor of the standardized overflow-wrap property.