sp-alert-banner

text
dismissible true false
open true false
variant Neutral Info Negative

NPM

1.0.0

Storybook

View Storybook
Examples API Changelog

Attributes and Properties #

Property Attribute Type Default Description dismissible dismissible boolean false Whether to include an icon-only close button to dismiss the alert banner open open boolean false Controls the display of the alert banner variant 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

1.0.0 (2024-10-31) #

Note: Version bump only for package @spectrum-web-components/alert-banner

0.49.0 (2024-10-15) #

Features #

  • add static-color to replace static (#4808) (43cf086)

0.48.1 (2024-10-01) #

Note: Version bump only for package @spectrum-web-components/alert-banner

0.48.0 (2024-09-17) #

Note: Version bump only for package @spectrum-web-components/alert-banner

0.47.2 (2024-09-03) #

Note: Version bump only for package @spectrum-web-components/alert-banner

0.47.1 (2024-08-27) #

Note: Version bump only for package @spectrum-web-components/alert-banner

0.47.0 (2024-08-20) #

Note: Version bump only for package @spectrum-web-components/alert-banner

0.46.0 (2024-08-08) #

Note: Version bump only for package @spectrum-web-components/alert-banner

0.45.0 (2024-07-30) #

Note: Version bump only for package @spectrum-web-components/alert-banner

0.44.0 (2024-07-15) #

Features #

  • alert-banner: add alert banner component (#4266) (10d456e)
  • Silder: adjust fillStart calculation for value=0 and normalization function (#4573) (369fee7), closes #4558

Description #

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

Usage #

See it on NPM! How big is this package in your project?

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';

When looking to leverage the AlertBanner base class as a type and/or for extension purposes, do so via:

import { AlertBanner } from '@spectrum-web-components/alert-banner';

Examples #

The alert banner accepts text context in the default slot provided:

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

Dismissible #

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>

Actionable #

Use the action slot for the contextual action that a user can take in response to the issue described:

<sp-alert-banner open dismissible>
    Your trial has expired
    <sp-button treatment="outline" static-color="white" slot="action">
        Buy now
    </sp-button>
</sp-alert-banner>

Variants #

Info #

<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 #

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

Closing the alert banner #

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 element is rendered with a role of alert, to inform screen readers and notify users accordingly. When rendering an alert that is dismissable or has actions on a page, it should be placed in a container with a role of region and that region should be labelled for screen readers users to quickly navigate.

The alert banner supports keyboard interaction as follows:

  • Tab should place focus on the next interactive element, which can be either the actionable button or the close button.
  • Tab + Shift should place focus on the previous interactive element.
  • Space or Enter should trigger the interaction if one of the buttons is focused, thus dismissing the alert in case of the close button or triggering the corresponding contextual action.
  • Esc will dismiss an alert banner if it’s a dismissible alert.

Once focus is on the alert banner, arrow keys can be used to navigate between the close button and the slotted action buttons.