@spectrum-web-components/alert-dialog

Overview

<sp-alert-dialog role="alertdialog" aria-labelledby="xx-heading" aria-describedby="xx-message" role="alertdialog" aria-labelledby="" aria-describedby=""> displays important information that users need to acknowledge. When used directly, the <sp-alert-dialog role="alertdialog" aria-labelledby="xx-heading" aria-describedby="xx-message" role="alertdialog" aria-labelledby="" aria-describedby=""> element surfaces a slot based API for deep customization of the content to be included in the overlay.

Usage

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

Import the side effectful registration of <sp-alert-dialog role="alertdialog" aria-labelledby="xx-heading" aria-describedby="xx-message" role="alertdialog" aria-labelledby="" aria-describedby=""> via:

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

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

import { AlertDialog } from '@spectrum-web-components/alert-dialog';

Anatomy

The alert dialog consists of several key parts:

• Title: All alert dialogs must have a title, using slot="heading", that uses a few words to convey the outcome of what will happen if a user continues with an action
• Content: Alert dialogs can include a description using the default slot. A description briefly communicates any additional information or context that a user needs to know to continue with an action
• Action buttons, using slot="button", that allow users to respond

<sp-alert-dialog
    role="alertdialog"
    aria-labelledby="example-heading"
    aria-describedby="example-message"
    variant="confirmation"
>
    <h2 id="example-heading" slot="heading">Important Notice</h2>
    <p id="example-message">This action requires your confirmation.</p>
    <sp-button
        slot="button"
        variant="secondary"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Cancel
    </sp-button>
    <sp-button
        slot="button"
        variant="accent"
        treatment="fill"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Confirm
    </sp-button>
</sp-alert-dialog>

Buttons

Use slot="button" to render your action button(s) that allow users to respond

• An alert dialog must have one primary action button (with variant="primary") with the option to include a secondary action and/or a cancel action.
• Non-primary action buttons should be variant="secondary" and treatment="outline".
• The three buttons should be rendered in the DOM in the following order:
  • Cancel action: Offers an option to go back and cancel the action.
  • Secondary action: Offers a secondary action. e.g. "Remind me later"
  • Primary action: The first (right-most) button communicates what the button will do if selected, or to acknowledge and dismiss the dialog. Check variants for the correct primary button styling. See also the Alert Dialog design options.

<sp-alert-dialog
    role="alertdialog"
    aria-labelledby="rate-heading"
    aria-describedby="rate-message"
    variant="information"
>
    <h2 id="rate-heading" slot="heading">Rate this app</h2>
    <p id="rate-message">
        If you enjoy our app, would you mind taking a moment to rate it?
    </p>
    <sp-button
        slot="button"
        variant="secondary"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        No, thanks
    </sp-button>
    <sp-button
        slot="button"
        variant="secondary"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Remind me later
    </sp-button>
    <sp-button
        slot="button"
        variant="primary"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Rate now
    </sp-button>
</sp-alert-dialog>

Options

Variants

The alert dialog supports confirmation, information, warning, error, and destructive variants to convey the nature and importance of the message:

Confirmation

Confirmation is the default variant for alert dialogs. Use a confirmation variant for asking a user to confirm a choice.

<sp-alert-dialog
    role="alertdialog"
    aria-labelledby="disclaimer-heading"
    aria-describedby="disclaimer-message"
    variant="confirmation"
>
    <h2 id="disclaimer-heading" slot="heading">Disclaimer</h2>
    <p id="disclaimer-message">
        Smart filters are nondestructive and will preserve your original images.
    </p>
    <sp-button
        slot="button"
        variant="secondary"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Cancel
    </sp-button>
    <sp-button
        slot="button"
        variant="accent"
        treatment="fill"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Enable
    </sp-button>
</sp-alert-dialog>

Information

Information alert dialogs communicate important information that a user needs to acknowledge. Before using this kind of alert dialog, make sure it’s the appropriate communication channel for the message instead of a toast or a more lightweight messaging option.

<sp-alert-dialog
    role="alertdialog"
    aria-labelledby="information-heading"
    aria-describedby="information-message"
    variant="information"
>
    <h2 id="information-heading" slot="heading">Connect to wifi</h2>
    <p id="information-message">
        Please connect to wifi to sync your projects or go to Settings to change
        your preferences.
    </p>
    <sp-button
        slot="button"
        variant="secondary"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Cancel
    </sp-button>
    <sp-button
        slot="button"
        variant="primary"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Continue
    </sp-button>
</sp-alert-dialog>

Warning

Warning alert dialogs communicate important information to users in relation to an issue that needs to be acknowledged, but does not block the user from moving forward.

<sp-alert-dialog
    role="alertdialog"
    aria-labelledby="warning-heading"
    aria-describedby="warning-message"
    variant="warning"
>
    <h2 id="warning-heading" slot="heading">Unverified format</h2>
    <p id="warning-message">
        This format has not been verified and may not be viewable for some
        users. Do you want to continue publishing?
    </p>
    <sp-button
        slot="button"
        variant="secondary"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Cancel
    </sp-button>
    <sp-button
        slot="button"
        variant="primary"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Continue
    </sp-button>
</sp-alert-dialog>

Error

Error alert dialogs communicate critical information about an issue that a user needs to acknowledge.

<sp-alert-dialog
    role="alertdialog"
    aria-labelledby="error-heading"
    aria-describedby="error-message"
    variant="error"
>
    <h2 id="error-heading" slot="heading">Unable to share</h2>
    <p id="error-message">
        An error occurred while sharing your project. Please verify the email
        address and try again.
    </p>
    <sp-button
        slot="button"
        variant="primary"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Continue
    </sp-button>
</sp-alert-dialog>

Destructive

Destructive alert dialogs are for when a user needs to confirm an action that will impact their data or experience in a potentially negative way, such as deleting files or contacts.

<sp-alert-dialog
    role="alertdialog"
    aria-labelledby="destructive-heading"
    aria-describedby="destructive-message"
    variant="destructive"
>
    <h2 id="destructive-heading" slot="heading">Delete 3 documents?</h2>
    <p id="destructive-message">
        Are you sure you want to delete the 3 selected documents?
    </p>
    <sp-button
        slot="button"
        variant="secondary"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Cancel
    </sp-button>
    <sp-button
        slot="button"
        variant="negative"
        treatment="outline"
        onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
    >
        Delete
    </sp-button>
</sp-alert-dialog>

Behaviors

Context

An alert dialog should be placed inside a modal overlay or a dialog base:

Modal overlay

<sp-button id="trigger">open modal</sp-button>
<sp-overlay trigger="trigger@click" type="modal" placement="bottom">
    <sp-popover>
        <sp-alert-dialog
            role="alertdialog"
            aria-labelledby="modal-heading"
            aria-describedby="modal-message"
            variant="confirmation"
        >
            <h2 id="modal-heading" slot="heading">Important Notice</h2>
            <p id="modal-message">This action requires your confirmation.</p>
            <sp-button
                slot="button"
                variant="secondary"
                treatment="outline"
                onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
            >
                Cancel
            </sp-button>
            <sp-button
                slot="button"
                variant="accent"
                treatment="fill"
                onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
            >
                Confirm
            </sp-button>
        </sp-alert-dialog>
    </sp-popover>
</sp-overlay>

Dialog base

<overlay-trigger type="modal">
    <sp-dialog-base underlay slot="click-content">
        <sp-alert-dialog
            role="alertdialog"
            aria-labelledby="modal-heading"
            aria-describedby="modal-message"
            variant="confirmation"
        >
            <h2 id="modal-heading" slot="heading">Important Notice</h2>
            <p id="modal-message">This action requires your confirmation.</p>
            <sp-button
                slot="button"
                variant="secondary"
                treatment="outline"
                onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
            >
                Cancel
            </sp-button>
            <sp-button
                slot="button"
                variant="accent"
                treatment="fill"
                onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
            >
                Confirm
            </sp-button>
        </sp-alert-dialog>
    </sp-dialog-base>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>

Accessibility

<sp-alert-banner> Element

• Use role="alertdialog" on the alert dialog
• Make sure the alert dialog has an aria-labelledby attribute that references the title's id.
• Make sure the alert dialog has an aria-describedby attribute that references the content's id.

Title

• Consider the appropriate variant based on the message's importance and urgency
• Use concise, meaningful dialog title that clearly states the purpose
• Use semantic heading elements (<h2>) for the dialog title

Content

• Provide clear, concise content that explains the situation and required actions

####Buttons

• Ensure button labels clearly indicate the action they will perform

Changelog

1.8.0 (2025-09-23)

Minor Changes

sp-picker: Fixed escape key behavior in modal overlays containing picker components. Previously, pressing the Escape key when a picker was open inside a modal overlay would not properly close the modal, instead moving focus to the picker. Now, the escape key correctly closes the picker first (if open), then closes the modal overlay on subsequent escape key presses.

This fix adds a check for this.open in the picker's handleEscape method to ensure proper modal overlay closure behavior.

sp-overlay: Added allow-outside-click property to <sp-overlay> with deprecation notice. This property allows clicks outside the overlay to close it, but is not recommended for accessibility reasons and will be removed in a future version.

This property is being added as deprecated to support the fallback for showModal() which was removed as part of performance optimization. We will no longer support outside clicks for modal overlays as they violate accessibility guidelines.

The property defaults to false and shows deprecation warnings when used. Consider using explicit close buttons or modal/page overlay types instead for better accessibility.

sp-menu: Fixed : Fix iPad scrolling issue in picker dropdown where scrolling through menu items would accidentally select the first touched item and close the picker.

The fix implements touch gesture detection to distinguish between scrolling and selection. Added isScrolling getter for public API access. Test on iPad devices with long menus to validate scrolling behavior and selection accuracy.

sp-overlay: Fixed : Added body scroll prevention for modal and page overlays. Overlay automatically blocks body scroll when modal or page overlays are open and restores the original scroll state when they are closed, improving user experience and accessibility for modal dialogs.

sp-clear-button: Clear button styles have been updated to the latest Spectrum CSS version of the clear button. This update includes a major reduction in the number of custom property abstractions needed to support the multiple theming layers (as seen in the styles package).

This update spans the following additional packages:

• @spectrum-web-components/button
• @spectrum-web-components/styles

As the updated styles now offer additional styling options, we have added the following API to the clear button component that exists in the button package:

• quiet - when set to true, the button will be rendered as a quiet button. This is useful for cases where you want to use the clear button in a more subtle way.
• disabled - when set to true, the button will be rendered as a disabled button.
• static-color - currently this only supports the white context color. This is useful for cases where the button appears on a dark background texture. This is a replacement for the previously used variant="overBackground" attribute which is deprecated.

Deprecation

The variant="overBackground" attribute is deprecated; please use the new static-color="white" attribute instead. When this property is used in the component, a deprecation warning will be shown in the console when in debug mode. The variant attribute will be removed in a future release.

sp-card: Fixed the card component's CSS by moving block-size: 100% from the base :host selector to only apply to gallery and quiet variants

sp-overlay: Fixed : external click registration behavior in the sp-overlay component. Programmatic clicks on elements outside of modal overlays now properly register and close the overlay, while user-initiated clicks are prevented from doing so.

sp-card: Enhanced the Card component's checkbox functionality with improved screen reader support and keyboard navigation.

Patch Changes

sp-progress-bar: Added: Deprecation warning for the over-background attribute.

sp-combobox: Replace the use of offsetWidth with a resizeObserver to avoid unecessary, performance-impacting layout reflows.

sp-styles: Bring the CJK font alias token fix from CSS #3883 4e3a120.

The --spectrum-cjk-font token was incorrectly mapped to the code font-family stack instead of --spectrum-cjk-font-family-stack. Thanks @byteakp!

sp-color-wheel: Fixed <sp-color-wheel> step attribute functionality for keyboard navigation. The step attribute now properly controls the increment size when using arrow keys to navigate the color wheel.

sp-switch: ### Fix down state colors for switch

Because the postcss-hover-media-feature plugin converts hover styles into a media query for devices that support hover, the hover styles were overriding any active/down state styles. We needed to target the active/down states of the switch with additional active state selectors, in order to ensure that the active state takes precedence over the hover state, maintaining the correct visual behavior of the switch component across different interaction states.

This fix should address hover + active state discrepancies in S1 and S2 foundations.

sp-contextual-help: Fixed a typo in the default info variant label from "Informations" to "Information".

Additionally, added package dependency for @spectrum-web-components/reactive-controllers@1.7.0.

sp-slider: Editable sliders will now reliably emit input events when interaction starts with the track.

sp-link: Fixed quiet variant links not showing keyboard focus state in Safari. Links with the quiet attribute now properly display focus indicators when navigating with keyboard, improving accessibility for keyboard users.

sp-progress-bar: Smooths the transition animation of indeterminate progress bar by overriding the incoming CSS, and positioning the animating fill element completely off of the progress bar track in both LTR and RTL languages. Before, the fill element was automatically starting on the track which led to a jarring animation loop.

sp-divider: Added: staticColor property to the Divider component, enabling programmatic control of the existing static color functionality.