@spectrum-web-components/alert-dialog

Overview

displays important information that users need to acknowledge. When used directly, the element surfaces a slot based API for deep customization of the content to be included in the overlay.

$3


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

Import the side effectful registration of via:

`javascript
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:

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

$3

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

`html
role="alertdialog"
aria-labelledby="example-heading"
aria-describedby="example-message"
variant="confirmation"
>


Important Notice

This action requires your confirmation.

slot="button"
variant="secondary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Cancel

slot="button"
variant="accent"
treatment="fill"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Confirm


`

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

`html
role="alertdialog"
aria-labelledby="rate-heading"
aria-describedby="rate-message"
variant="information"
>


Rate this app

If you enjoy our app, would you mind taking a moment to rate it?

slot="button"
variant="secondary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
No, thanks

slot="button"
variant="secondary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Remind me later

slot="button"
variant="primary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Rate now


`

$3

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

`html
role="alertdialog"
aria-labelledby="disclaimer-heading"
aria-describedby="disclaimer-message"
variant="confirmation"
>


Disclaimer

Smart filters are nondestructive and will preserve your original images.

slot="button"
variant="secondary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Cancel

slot="button"
variant="accent"
treatment="fill"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Enable


`

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.

`html
role="alertdialog"
aria-labelledby="information-heading"
aria-describedby="information-message"
variant="information"
>


Connect to wifi

Please connect to wifi to sync your projects or go to Settings to change
your preferences.

slot="button"
variant="secondary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Cancel

slot="button"
variant="primary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Continue


`

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.

`html
role="alertdialog"
aria-labelledby="warning-heading"
aria-describedby="warning-message"
variant="warning"
>


Unverified format

This format has not been verified and may not be viewable for some
users. Do you want to continue publishing?

slot="button"
variant="secondary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Cancel

slot="button"
variant="primary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Continue


`

Error

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

`html
role="alertdialog"
aria-labelledby="error-heading"
aria-describedby="error-message"
variant="error"
>


Unable to share

An error occurred while sharing your project. Please verify the email
address and try again.

slot="button"
variant="primary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Continue


`

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.

`html
role="alertdialog"
aria-labelledby="destructive-heading"
aria-describedby="destructive-message"
variant="destructive"
>


Delete 3 documents?

Are you sure you want to delete the 3 selected documents?

slot="button"
variant="secondary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Cancel

slot="button"
variant="negative"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Delete


`

$3

#### Context

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

Modal overlay

`html
open modal


role="alertdialog"
aria-labelledby="modal-heading"
aria-describedby="modal-message"
variant="confirmation"
>


Important Notice

This action requires your confirmation.

slot="button"
variant="secondary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Cancel

slot="button"
variant="accent"
treatment="fill"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Confirm




`

Dialog base

`html


role="alertdialog"
aria-labelledby="modal-heading"
aria-describedby="modal-message"
variant="confirmation"
>


Important Notice

This action requires your confirmation.

slot="button"
variant="secondary"
treatment="outline"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Cancel

slot="button"
variant="accent"
treatment="fill"
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
>
Confirm



Toggle Dialog

`

$3

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

`) 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