Dialog
A modal window over the page: the rest of the page is inert until it closes. Used for a focused task (search, a short form, a confirmation). Eight custom elements share the open state through context.
Tag <sb-dialog> · status stable · version 0.1.0
Example
<sb-dialog>
<sb-dialog-trigger><sb-button variant="tertiary">Edit profile</sb-button></sb-dialog-trigger>
<sb-dialog-content>
<sb-dialog-header>
<sb-dialog-title>Edit profile</sb-dialog-title>
<sb-dialog-description>Make changes to your profile here. Save when you are done.</sb-dialog-description>
</sb-dialog-header>
<sb-dialog-footer>
<sb-dialog-close><sb-button variant="tertiary">Cancel</sb-button></sb-dialog-close>
<sb-dialog-close><sb-button>Save changes</sb-button></sb-dialog-close>
</sb-dialog-footer>
</sb-dialog-content>
</sb-dialog>
Properties
| Name | Type | Default | Notes |
|---|---|---|---|
open |
boolean | false |
Whether the dialog is showing. The trigger, the close controls, Escape and a backdrop click change it; code can set it too. Set on first render, the dialog opens as soon as it is connected. |
Events
| Name | Notes |
|---|---|
sb-toggle |
fires on the sb-dialog host after open changes, from a person or from code (like the native dialog's toggle and Collapsible). Read host.open for the new state. Bubbles and is composed, so a listener on an outer dialog also receives a nested dialog's sb-toggle: check event.target. |
sb-cancel |
fires on the sb-dialog host before Escape or a backdrop click closes the dialog (like the native dialog's cancel). preventDefault() keeps it open, for example to confirm discarding unsaved input. Not fired for the close button, sb-dialog-close or code. Bubbles and is composed, so a listener on an outer dialog also receives a nested dialog's sb-cancel: check event.target before calling preventDefault(). |
Parts
<sb-dialog-content>
The modal surface: a bordered, shadowed panel centered over a dimmed backdrop, with a close button in its top inline-end corner.
| Name | Type | Default | Notes |
|---|---|---|---|
hideCloseButton |
boolean | false |
Hides the built-in close button. Named so the attribute is off by default (the visual reference shows the button by default). Keep another visible way to close, such as a Cancel button in sb-dialog-close (APG). |
closeLabel |
text | Close |
Accessible name of the built-in close button. Translate it. |
Keyboard
| Key | Does |
|---|---|
Escape |
close the dialog (fires sb-cancel first; a prevented sb-cancel keeps it open); ignored while an input method is composing text |
Tab |
move to the next focusable element inside the dialog; from the last it wraps to the first (Shift+Tab from the first wraps to the last); the page behind is inert |
Shift+Tab |
move to the previous focusable element inside the dialog |
Enter |
on the trigger's control, open the dialog |
Space |
on the trigger's control, open the dialog |
Accessibility
- Role:
dialog (modal) - Native element:
dialog - Accessible name: the sb-dialog-title text, through an element reference (ID references do not cross shadow roots, SB-0009); with no title, host aria-label on sb-dialog-content is forwarded. The description, when present, is the accessible description.