sp-dialog-wrapper

NPM 1.6.0

View Storybook

Try it on webcomponents.dev
Overview API

Overview

sp-dialog-wrapper supplies an attribute-based interface for the managed customization of an sp-dialog element and the light DOM supplied to it. This is paired it with an underlay attribute that opts-in to the use of an sp-underlay element between your page content and the sp-dialog that opens over it.

Usage

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/dialog

Import the side effectful registration of <sp-dialog-wrapper> via:

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

Anatomy

The dialog wrapper is a high-level component that combines the sp-dialog-base functionality and the sp-dialog layout and stylingwith an attribute-based API.

The dialog wrapper consists of several key parts:

  • A headline used as the dialog title (via the headline attribute)
  • Content (via default slot)
  • Optional hero content (via the hero attribute)
  • Optional footer content (via the footer attribute)
  • Optional underlay (via the underlay attribute)
  • Optional buttons (via the confirm-label, cancel-label, and secondary-label attributes)
  • Optional dismiss button (via the dismissable attribute and the dismiss-label attribute)
<overlay-trigger type="modal">
    <sp-dialog-wrapper
        slot="click-content"
        headline="Dialog title"
        hero="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
        confirm-label="Confirm"
        cancel-label="Cancel"
        secondary-label="Secondary"
        underlay
        footer="Content for footer"
    >
        Content of the dialog
    </sp-dialog-wrapper>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>

Options

Sizes

The dialog wrapper supports different sizes via the size attribute: s, m, l.

Small Medium 
<overlay-trigger type="modal">
    <sp-dialog-wrapper
        size="m"
        slot="click-content"
        headline="Dialog title"
        dismissable
        dismiss-label="Close"
        underlay
        footer="Content for footer"
    >
        Content of the dialog
    </sp-dialog-wrapper>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>
 Large

Underlay

The underlay attribute can be used to add an underlay element between the page content and the dialog.

With underlay 
<overlay-trigger type="modal">
    <sp-dialog-wrapper
        slot="click-content"
        headline="Dialog title"
        dismissable
        dismiss-label="Close"
        underlay
        footer="Content for footer"
    >
        Content of the dialog
    </sp-dialog-wrapper>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>
 Without underlay

Dismissable

The dismissable attribute can be used to add an underlay element between the page content and the dialog.

Dismissable 
<overlay-trigger type="modal">
    <sp-dialog-wrapper
        slot="click-content"
        headline="Dialog title"
        dismissable
        dismiss-label="Close"
        underlay
        footer="Content for footer"
    >
        Content of the dialog
    </sp-dialog-wrapper>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>
 Not dismissable

Mode

The dialog wrapper supports different display modes:

Fullscreen 
<overlay-trigger type="modal">
    <sp-dialog-wrapper
        slot="click-content"
        headline="Dialog title"
        cancel-label="Cancel"
        underlay
        footer="Content for footer"
        mode="fullscreen"
    >
        Content of the dialog
    </sp-dialog-wrapper>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>
 Fullscreen Takeover

Accessibility

Include a headline

An sp-dialog-wrapper element leverages the headline attribute/property to label the dialog content for screen readers. The headline-visibility attribute will accept a value of "none" to suppress the headline visually.

Manage focus

The dialog wrapper component ensures proper focus management by:

  • Moving focus into the dialog when opened
  • Trapping tab order within the dialog while open
  • Returning focus to the trigger element when closed

The receives-focus attribute can be used to control whether the dialog should receive focus when it is opened. Leverage the type="modal" and receives-focus="auto" settings in the Overlay API to ensure that focus is thrown into the dialog content when opened and that the tab order will be trapped within it while open.

The receives-focus attribute on overlay-trigger has three possible values:

  • auto (default): Focus will automatically move to the first focusable element in the dialog
  • true: Forces focus to move to the overlay content
  • false: Prevents focus from moving to the overlay

For accessible dialogs, always use receives-focus="auto" or receives-focus="true" to ensure keyboard users can interact with the dialog content.

<overlay-trigger type="modal" receives-focus="true">
    <sp-dialog-wrapper
        slot="click-content"
        headline="Dialog title"
        dismissable
        dismiss-label="Close"
        underlay
        footer="Content for footer"
        mode="fullscreenTakeover"
    >
        Content of the dialog
    </sp-dialog-wrapper>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>