@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