sp-dialog-base

NPM 1.5.0

View Storybook

Try it on webcomponents.dev
Overview API

Overview

sp-dialog-base accepts slotted dialog content (often an <sp-dialog>) and presents that content in a container that is animated into place when toggling the open attribute. In concert with the Overlay API or Overlay Trigger, the provided dialog content will be displayed over the rest of the page.

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-base> via:

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

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

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

Anatomy

The dialog base consists of a single default slot that expects an sp-dialog element to be provided. The dialog base manages the presentation and animation of this content.

<overlay-trigger type="modal">
    <sp-dialog-base slot="click-content">
        <sp-dialog>
            <h2 slot="heading">A thing is about to happen</h2>
            <p>Something that might happen a lot is about to happen.</p>
            <p>
                The click events for the "OK" button are bound to the story not
                to the components in specific.
            </p>
            <sp-button
                variant="secondary"
                treatment="fill"
                slot="button"
                onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
            >
                Ok
            </sp-button>
            <sp-checkbox slot="footer">Don't show me this again</sp-checkbox>
        </sp-dialog>
    </sp-dialog-base>
    <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 
<overlay-trigger type="modal">
    <sp-dialog-base underlay slot="click-content" size="s">
        <sp-dialog size="s" dismissable>
            <h2 slot="heading">A thing is about to happen</h2>
            <p>Something that might happen a lot is about to happen.</p>
        </sp-dialog>
    </sp-dialog-base>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>
 Medium 
<overlay-trigger type="modal">
    <sp-dialog-base underlay slot="click-content" size="m">
        <sp-dialog dismissable>
            <h2 slot="heading">A thing is about to happen</h2>
            <p>Something that might happen a lot is about to happen.</p>
        </sp-dialog>
    </sp-dialog-base>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>
 Large 
<overlay-trigger type="modal">
    <sp-dialog-base underlay slot="click-content" size="l">
        <sp-dialog dismissable>
            <h2 slot="heading">A thing is about to happen</h2>
            <p>Something that might happen a lot is about to happen.</p>
        </sp-dialog>
    </sp-dialog-base>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>

Underlay

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

</style>
<overlay-trigger type="modal">
    <sp-dialog-base underlay slot="click-content">
        <sp-dialog>
            <h2 slot="heading">A thing is about to happen</h2>
            <p>Something that might happen a lot is about to happen.</p>
            <p>
                The click events for the "OK" button are bound to the story not
                to the components in specific.
            </p>
            <sp-button
                variant="secondary"
                treatment="fill"
                slot="button"
                onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
            >
                Ok
            </sp-button>
            <sp-checkbox slot="footer">Don't show me this again</sp-checkbox>
        </sp-dialog>
    </sp-dialog-base>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>

Dismissable

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

</style>
<overlay-trigger type="modal">
    <sp-dialog-base underlay slot="click-content">
        <sp-dialog dismissable>
            <h2 slot="heading">A thing is about to happen</h2>
            <p>Something that might happen a lot is about to happen.</p>
        </sp-dialog>
    </sp-dialog-base>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>

Mode

The dialog base supports different display modes:

Fullscreen Mode
<overlay-trigger type="modal">
    <sp-dialog-base underlay mode="fullscreen" slot="click-content">
        <sp-dialog dismissable>
            <h2 slot="heading">A thing is about to happen</h2>
            <p>Something that might happen a lot is about to happen.</p>
        </sp-dialog>
    </sp-dialog-base>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>
Fullscreen Takeover Mode
<overlay-trigger type="modal">
    <sp-dialog-base underlay mode="fullscreenTakeover" slot="click-content">
        <sp-dialog dismissable>
            <h2 slot="heading">A thing is about to happen</h2>
            <p>Something that might happen a lot is about to happen.</p>
            <p>
                The click events for the "OK" button are bound to the story not
                to the components in specific.
            </p>
        </sp-dialog>
    </sp-dialog-base>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>

Behaviors

The dialog base manages several behaviors:

  1. Animation of the dialog content when opening/closing
  2. Focus management when the dialog opens
  3. Event handling for closing the dialog

Receives focus

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.

<overlay-trigger type="modal" receives-focus="auto">
    <sp-dialog-base underlay mode="fullscreenTakeover" slot="click-content">
        <sp-dialog dismissable>
            <h2 slot="heading">A thing is about to happen</h2>
            <p>Something that might happen a lot is about to happen.</p>
            <p>
                The click events for the "OK" button are bound to the story not
                to the components in specific.
            </p>
        </sp-dialog>
    </sp-dialog-base>
    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
</overlay-trigger>

Accessibility

The dialog base 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

See the Dialog component for more information on the accessibility features of the dialog content.

Attributes and Properties

Property Attribute Type Default Description dismissable dismissable boolean false mode mode 'fullscreen' | 'fullscreenTakeover' | undefined open open boolean false responsive responsive boolean false When set to true, fills screens smaller than 350px high and 400px wide with the full dialog. underlay underlay boolean false

Slots

Name Description default slot A Dialog element to display.

Events

Name Type Description close Event Announces that the dialog has been closed. undefined TransitionEvent