sp-alert-banner

text

dismissible

true

false

open

true

false

variant

Neutral

Info

Negative

NPM 1.5.0

View Storybook

Overview

API

Changelog

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

Attributes and Properties

Property

Attribute

Type

Default

Description

dismissible

boolean

false

Whether to include an icon-only close button to dismiss the alert banner

open

boolean

false

Controls the display of the alert banner

variant

AlertBannerVariants

The variant applies specific styling when set to `negative` or `info`; `variant` attribute is removed when it's passed an invalid variant.

Slots

Name

Description

default slot

The alert banner text context

action

Slot for the button element that surfaces the contextual action a user can take

Events

Name

Type

Description

close

CustomEvent

Announces the alert banner has been closed

Patch Changes

#5271 165a904 Thanks @renovate! - Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.
Updated dependencies [4e06533]:
- @spectrum-web-components/button@1.5.0
- @spectrum-web-components/icons-workflow@1.5.0
- @spectrum-web-components/base@1.5.0

1.4.0

Patch Changes

Updated dependencies []:
- @spectrum-web-components/button@1.4.0
- @spectrum-web-components/icons-workflow@1.4.0
- @spectrum-web-components/base@1.4.0

1.3.0

Patch Changes

Updated dependencies []:
- @spectrum-web-components/button@1.3.0
- @spectrum-web-components/icons-workflow@1.3.0
- @spectrum-web-components/base@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.