sp-alert-dialog

NPM 1.6.0

View Storybook
Overview API Changelog

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

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

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 Warning Error Destructive

Behaviors

Context

An alert dialog should be placed inside a modal overaly:

<sp-button id="trigger">open modal</sp-button>
<sp-overlay trigger="trigger@click" type="modal">
    <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-overlay>

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