sp-dialog
displays important information that users need to acknowledge. They appear over the interface and block further interactions. When used directly the sp-dialog
element surfaces a slot
based API for deep customization of the content to be included in the overlay.
Note: the sp-dialog
element is a component that is used to create a dialog layout. For modal and popover behavior, it should be used within a component that manages the overlay state.

yarn add @spectrum-web-components/dialog
Import the side effectful registration of <sp-dialog>
via:
import '@spectrum-web-components/dialog/sp-dialog.js';
When looking to leverage the Dialog
base class as a type and/or for extension purposes, do so via:
import { Dialog } from '@spectrum-web-components/dialog';
The dialog consists of several key parts:
- A heading (via
slot="heading"
) - Content (via default slot)
- Optional hero content (via
slot="hero"
) - Optional buttons (via
slot="button"
) - Optional footer content (via
slot="footer"
) - Optional dismiss button (via
dismissable
attribute)
<sp-dialog size="s">
<div
slot="hero"
style="background-image: url(https://picsum.photos/1400/260)"
></div>
<h2 slot="heading">Disclaimer</h2>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
<div slot="footer">Footer information</div>
<sp-button slot="button">Button</sp-button>
</sp-dialog>
Small <sp-dialog size="s">
<h2 slot="heading">Disclaimer</h2>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris
augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas diam
in arcu cursus euismod quis viverra. Posuere ac ut consequat semper viverra
nam libero justo laoreet. Enim ut tellus elementum sagittis vitae et leo
duis ut. Neque laoreet suspendisse interdum consectetur libero id faucibus
nisl. Diam volutpat commodo sed egestas egestas. Dolor magna eget est lorem
ipsum dolor. Vitae suscipit tellus mauris a diam maecenas sed. Turpis in eu
mi bibendum neque egestas congue. Rhoncus est pellentesque elit ullamcorper
dignissim cras lobortis.
</sp-dialog>
Medium <sp-dialog size="m">
<h2 slot="heading">Disclaimer</h2>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris
augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas diam
in arcu cursus euismod quis viverra. Posuere ac ut consequat semper viverra
nam libero justo laoreet. Enim ut tellus elementum sagittis vitae et leo
duis ut. Neque laoreet suspendisse interdum consectetur libero id faucibus
nisl. Diam volutpat commodo sed egestas egestas. Dolor magna eget est lorem
ipsum dolor. Vitae suscipit tellus mauris a diam maecenas sed. Turpis in eu
mi bibendum neque egestas congue. Rhoncus est pellentesque elit ullamcorper
dignissim cras lobortis.
</sp-dialog>
Large <sp-dialog size="l">
<h2 slot="heading">Disclaimer</h2>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris
augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas diam
in arcu cursus euismod quis viverra. Posuere ac ut consequat semper viverra
nam libero justo laoreet. Enim ut tellus elementum sagittis vitae et leo
duis ut. Neque laoreet suspendisse interdum consectetur libero id faucibus
nisl. Diam volutpat commodo sed egestas egestas. Dolor magna eget est lorem
ipsum dolor. Vitae suscipit tellus mauris a diam maecenas sed. Turpis in eu
mi bibendum neque egestas congue. Rhoncus est pellentesque elit ullamcorper
dignissim cras lobortis.
</sp-dialog>
When supplied with the dissmissable
attribute an <sp-dialog>
element will surface a "close" button afordance that will dispatch a DOM event with the name of close
when pressed.
Note: the dissmissable
attribute will not be followed when mode="fullscreen"
or mode="fullscreenTakeover"
are applies in accordance with the Spectrum specification.
<sp-dialog dismissable>
<h2 slot="heading">Disclaimer</h2>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris
augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas diam
in arcu cursus euismod quis viverra. Posuere ac ut consequat semper viverra
nam libero justo laoreet. Enim ut tellus elementum sagittis vitae et leo
duis ut. Neque laoreet suspendisse interdum consectetur libero id faucibus
nisl. Diam volutpat commodo sed egestas egestas. Dolor magna eget est lorem
ipsum dolor. Vitae suscipit tellus mauris a diam maecenas sed. Turpis in eu
mi bibendum neque egestas congue. Rhoncus est pellentesque elit ullamcorper
dignissim cras lobortis.
</sp-dialog>
<sp-dialog dismissable no-divider>
<h2 slot="heading">Disclaimer</h2>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris
augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas diam
in arcu cursus euismod quis viverra. Posuere ac ut consequat semper viverra
nam libero justo laoreet. Enim ut tellus elementum sagittis vitae et leo
duis ut. Neque laoreet suspendisse interdum consectetur libero id faucibus
nisl. Diam volutpat commodo sed egestas egestas. Dolor magna eget est lorem
ipsum dolor. Vitae suscipit tellus mauris a diam maecenas sed. Turpis in eu
mi bibendum neque egestas congue. Rhoncus est pellentesque elit ullamcorper
dignissim cras lobortis.
</sp-dialog>
Use the dialog with an overlay to create a dialog that appears over the current page. The dialog manages several behaviors:
- Animation of the dialog content when opening/closing
- Focus management when the dialog opens
- Event handling for closing the dialog
<sp-button id="trigger">Overlay Trigger</sp-button>
<sp-overlay trigger="trigger@click" placement="bottom">
<sp-popover>
<sp-dialog>
<h2 slot="heading">Overlay 1</h2>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Auctor
augue mauris augue neque gravida. Libero volutpat sed ornare arcu.
</sp-dialog>
</sp-popover>
</sp-overlay>
<overlay-trigger placement="top" type="replace">
<sp-button slot="trigger">Overlay Trigger 2</sp-button>
<sp-popover slot="click-content" open>
<sp-dialog size="s">
<h2 slot="heading">Overlay 2</h2>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Auctor
augue mauris augue neque gravida. Libero volutpat sed ornare arcu.
<sp-button
slot="button"
onclick="javascript: this.dispatchEvent(new Event('close', {bubbles: true, composed: true}));"
>
I understand
</sp-button>
</sp-dialog>
</sp-popover>
</overlay-trigger>
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.
<sp-button id="focus">Overlay Trigger</sp-button>
<sp-overlay trigger="focus@click" type="modal" receives-focus="auto">
<sp-popover>
<sp-dialog>
<h2 slot="heading">Dialog Heading</h2>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Auctor
augue mauris augue neque gravida. Libero volutpat sed ornare arcu.
</sp-dialog>
</sp-popover>
</sp-overlay>
The heading
slot is of the sp-dialog
dialog element is used to label the dialog content for screen readers.
Changelog
- Updated dependencies [
f6cebbd
, 00eb0a8
]: - @spectrum-web-components/icons-workflow@1.6.0
- @spectrum-web-components/button@1.6.0
- @spectrum-web-components/alert-dialog@1.6.0
- @spectrum-web-components/button-group@1.6.0
- @spectrum-web-components/divider@1.6.0
- @spectrum-web-components/modal@1.6.0
- @spectrum-web-components/underlay@1.6.0
- @spectrum-web-components/base@1.6.0
- @spectrum-web-components/shared@1.6.0
- Updated dependencies [
165a904
, 4e06533
]: - @spectrum-web-components/alert-dialog@1.5.0
- @spectrum-web-components/button-group@1.5.0
- @spectrum-web-components/divider@1.5.0
- @spectrum-web-components/modal@1.5.0
- @spectrum-web-components/underlay@1.5.0
- @spectrum-web-components/button@1.5.0
- @spectrum-web-components/icons-workflow@1.5.0
- @spectrum-web-components/base@1.5.0
- @spectrum-web-components/shared@1.5.0
- Updated dependencies []:
- @spectrum-web-components/alert-dialog@1.4.0
- @spectrum-web-components/button@1.4.0
- @spectrum-web-components/button-group@1.4.0
- @spectrum-web-components/divider@1.4.0
- @spectrum-web-components/icons-workflow@1.4.0
- @spectrum-web-components/modal@1.4.0
- @spectrum-web-components/underlay@1.4.0
- @spectrum-web-components/base@1.4.0
- @spectrum-web-components/shared@1.4.0
-
#5176 468314f
Thanks @TarunAdobe! - 1. chore(checkbox): updated to latest css v10.1.1 for s2 fast follow
- chore(dialog): The error property was not properly deprecated with a full migration plan in place. This has caused confusion and false sense of urgency for consumers to migrate. We are removing it to eliminate those pain points for consumers while we take a deep look at our dialogs and patterns.
- chore(menu): updated to latest css v9.1.1 for s2 fast follow
- fix(overlay): sp-overlay with type="manual" should close on pressing ESC key. When the last item is on overlay stack we are triggering the close method on esc key event.
-
Updated dependencies []:
- @spectrum-web-components/button@1.3.0
- @spectrum-web-components/alert-dialog@1.3.0
- @spectrum-web-components/button-group@1.3.0
- @spectrum-web-components/divider@1.3.0
- @spectrum-web-components/icons-workflow@1.3.0
- @spectrum-web-components/modal@1.3.0
- @spectrum-web-components/underlay@1.3.0
- @spectrum-web-components/base@1.3.0
- @spectrum-web-components/shared@1.3.0
All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- lock prerelease versions for Spectrum CSS (#5014) (8aa7734)
- add an optional chromatic vrt action (7d2f840)
- dialog: fade-out animation when lazy loaded on popover overlays (#4937) (d36fc6e)
Note: Version bump only for package @spectrum-web-components/dialog
- dialog-wrapper: update heading to fully span grid area (#4810) (7d1f461)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- upgrade menu and dialog grid css (#4638) (ab9d468)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- dialog-wrapper: add dismiss-label attribute for the close button's label (#4154) (c450a09)
- styles, theme: surface exports that omit Spectrum Vars proactively (#4142) (5b524c1)
- asset: use core tokens (99e76f4)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- tray: only allow "click" events when they "pointerdown"ed on the Underlay (#4020) (4f9aa4a)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- alert-dialog: use resize observer in place of page resize event for content measurement work (b963813)
- alert-dialog: add Alert Dialog package (#3501) (1062847)
- dialog: include tab order management at slotchange time (0c7a079)
- dialog: leverage Overlay v2 (5c21ab5)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- overlay: ensure CSS calcs resolve to the expected measurement value (51a3feb)
- popover: use core tokens (68328cc)
Note: Version bump only for package @spectrum-web-components/dialog
- add docs and address PR comments (568062a)
- add grid areas workaround locally until available in Spectrum CSS (4c5ed9d)
- allow ActiveOverlay to manage open state (a7c4cff)
- centralize updated first focusable selector (300e84c)
- correct the relationship between overlayWillCloseCallback and phased animations (c63db8d)
- dialog: dialog wrapper headline a11y (205e8f7)
- dialog: don't show DialogWrapper divider when there's no headline (b46f724)
- dialog: ensure :focus-visible polyfill availability (b50e396)
- dialog: include all dependencies (9be0da0)
- dialog: include all dependencies (7090320)
- dialog: more complete support for Spectrum CSS input (925934a)
- dialog: normalize sizing technique to align with future t-shirt size usage (da33797)
- dialog: prevent "fullscreen*" dialogs from being "dissmisable" (c3a6420)
- dialog: support "error" in wrapper, prevent undelay closure when not dismissable (6789102)
- dialog: swap secondary and cancel button order (3df1705)
- dialog: updates for delivering dialog content accessibly (f0ed33c)
- dialog: use default value for "resolveTransitionPromise" for open by default dialogs (7317a3f)
- dialog: use styles from the modal package (0f04ce1)
- ensure browser understandable extensions (f4e59f7)
- have sp-dialog-wrapper confirm scroll management of its dialog when opening (fed9536)
- include default export in the "exports" fields (f32407d)
- include the "types" entry in package.json files (b432f59)
- match footer default color to content (fd2b6f9)
- prevent "hover" overlays from returning focus to the root of a parent modal (ceb8fa7)
- prevent Dialog Wrapper from dispatching two "close" events (be6d23b)
- prevent reuse of applied IDs when associating Dialogs to their content (962c3e8)
- pull out rendering for Dialog into individual methods (84aa3ec)
- remove nothing update (b066ebc)
- stop merging selectors in a way that alters the cascade (369388f)
- update latest Spectrum CSS beta releases (d8d3acc)
- update side effect listings (8160d3a)
- update to latest spectrum-css packages (a5ca19f)
- use icons without "size" values (3fc7c91)
- action-button: add action button pattern (03ac00a)
- add dialog, dialog-wrapped, and underlay elements (3df9050)
- adopt DNA@7 base Spectrum CSS (e08cafd)
- dialog: descendent attribute support, responsive attribute added (568cedb)
- dialog: update spectrum css input (405ca5e)
- dialog: use latest @spectrum-css/dialog beta (b5d5718)
- include all Dev Mode files in side effects (f70817c)
- leverage "exports" field in package.json (321abd7)
- leverage latest Spectrum button API (9caf2f6)
- overlay: manage focus throwing and tab trapping (27a0b53)
- picker: support responsive delivery of menu (20031d1)
- shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
- update to Spectrum CSS v3.0.0 (e8b3d8f)
- use latest exports specification (a7ecf4b)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- dialog: dialog wrapper headline a11y (205e8f7)
- dialog: don't show DialogWrapper divider when there's no headline (b46f724)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- correct the relationship between overlayWillCloseCallback and phased animations (c63db8d)
- prevent reuse of applied IDs when associating Dialogs to their content (962c3e8)
- add docs and address PR comments (568062a)
- add grid areas workaround locally until available in Spectrum CSS (4c5ed9d)
- prevent "hover" overlays from returning focus to the root of a parent modal (ceb8fa7)
- dialog: swap secondary and cancel button order (3df1705)
- include all Dev Mode files in side effects (f70817c)
- pull out rendering for Dialog into individual methods (84aa3ec)
- remove nothing update (b066ebc)
Note: Version bump only for package @spectrum-web-components/dialog
- prevent Dialog Wrapper from dispatching two "close" events (be6d23b)
- dialog: use default value for "resolveTransitionPromise" for open by default dialogs (7317a3f)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- leverage latest Spectrum button API (9caf2f6)
- dialog: updates for delivering dialog content accessibly (f0ed33c)
- picker: support responsive delivery of menu (20031d1)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- centralize updated first focusable selector (300e84c)
- adopt DNA@7 base Spectrum CSS (e08cafd)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- dialog: normalize sizing technique to align with future t-shirt size usage (da33797)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- have sp-dialog-wrapper confirm scroll management of its dialog when opening (fed9536)
- match footer default color to content (fd2b6f9)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- use latest exports specification (a7ecf4b)
- update to latest spectrum-css packages (a5ca19f)
Note: Version bump only for package @spectrum-web-components/dialog
- allow ActiveOverlay to manage open state (a7c4cff)
- dialog: ensure :focus-visible polyfill availability (b50e396)
- dialog: include all dependencies (9be0da0)
- dialog: more complete support for Spectrum CSS input (925934a)
- dialog: prevent "fullscreen*" dialogs from being "dissmisable" (c3a6420)
- include the "types" entry in package.json files (b432f59)
- stop merging selectors in a way that alters the cascade (369388f)
- update latest Spectrum CSS beta releases (d8d3acc)
- use icons without "size" values (3fc7c91)
- dialog: support "error" in wrapper, prevent undelay closure when not dismissable (6789102)
- dialog: use styles from the modal package (0f04ce1)
- action-button: add action button pattern (03ac00a)
- dialog: update spectrum css input (405ca5e)
- dialog: use latest @spectrum-css/dialog beta (b5d5718)
- use icons without "size" values (3fc7c91)
- dialog: more complete support for Spectrum CSS input (925934a)
- include the "types" entry in package.json files (b432f59)
- stop merging selectors in a way that alters the cascade (369388f)
- dialog: support "error" in wrapper, prevent undelay closure when not dismissable (6789102)
- update latest Spectrum CSS beta releases (d8d3acc)
- dialog: use styles from the modal package (0f04ce1)
- action-button: add action button pattern (03ac00a)
- dialog: update spectrum css input (405ca5e)
- dialog: use latest @spectrum-css/dialog beta (b5d5718)
- dialog: include all dependencies (7090320)
- include default export in the "exports" fields (f32407d)
- update side effect listings (8160d3a)
Note: Version bump only for package @spectrum-web-components/dialog
- update to Spectrum CSS v3.0.0 (e8b3d8f)
Note: Version bump only for package @spectrum-web-components/dialog
Note: Version bump only for package @spectrum-web-components/dialog
- ensure browser understandable extensions (f4e59f7)
Note: Version bump only for package @spectrum-web-components/dialog
- overlay: manage focus throwing and tab trapping (27a0b53)
- leverage "exports" field in package.json (321abd7)
Note: Version bump only for package @spectrum-web-components/dialog
- add dialog, dialog-wrapped, and underlay elements (3df9050)
- dialog: descendent attribute support, responsive attribute added (568cedb)