Dialog

A dialog serves as a container for in-page contextual information or actions, allowing users to confirm or cancel tasks without navigating away from the current page.

Usage

Code

Accessibility

Open dialogDialog title Dolore nulla ad magna nostrud cillum veniam sint et consectetur anim Lorem. Sint fugiat id deserunt magna et tempor veniam eu fugiat fugiat. Fugiat mollit sint labore adipisicing do mollit eu dolore nulla enim cillum.

Pariatur amet occaecat dolor consectetur aliqua mollit est aliquip irure cupidatat. Reprehenderit consectetur anim sunt voluptate dolor aute non enim aliqua sit. Occaecat irure ullamco aliquip minim labore occaecat dolor magna duis. Voluptate tempor amet cupidatat officia labore ipsum ad do.Close

<!--The trigger-->
<sl-button id="open-button" fill="solid" variant="primary">Open dialog</sl-button>

<!--The dialog-->
<sl-dialog id="dialog-example">
  <span slot="title">Dialog title</span>
  Dolore nulla ad magna nostrud cillum...
  <sl-button slot="actions" sl-dialog-close autofocus>Close</sl-button>
</sl-dialog>

When to use

The following guidance describes when to use the Dialog component.

Critical information

Use dialogs to present critical information or ask for decisions. For instance, when confirming a high-risk action (e.g., deleting data), a dialog ensures user attention.

Short tasks

For quick tasks that don’t warrant a full page transition, use dialogs. They allow users to stay within the context of their current workflow.

When not to use

The following guidance describes when not to use the Dialog component.

Complex data

Don’t overload dialogs with extensive data or complex interactions. Keep them concise.

Premature triggers

Only show dialogs when the user explicitly triggers them. Avoid interrupting the user unnecessarily.

Anatomy

Item	Name	Description	Optional
1	Overlay	Obscures the page content behind the panel	No
2	Panel	Contains the header, subheader, panel content and actions	No
3	Header	An area to display content at the top of the panel (e.g. title)	Yes
4	Subheader	An area to display the description of the title	Yes
5	Close button	Icon button for closing the dialog	Yes
6	Content	An area to display any content	Yes

Figma Options

With these options, you can tweak the appearance of the dialog in Figma. They are available in the Design Panel so you can compose the dialog to exactly fit the user experience need for the use case you are working on.

Item	Options	Description
Device	`desktop` `mobile`	Select the device for your prototype to ensure an optimal layout.
Size	`sm` `md (default)` `lg` `xl`	The dialog come in four sizes: small, medium (default), large and extra large, providing flexibility to align with your design requirements.
Close Icon	`boolean`	Choose if you want to show a close button.
Header Order	`title` `subtitle`	Choose if you want to start with the title or subtitle.
Content	`boolean`	Choose if you want to show content (slot component).
Slot Component	`.slot`	Select your own component to display within the dialog component.
Actions	`boolean`	Choose if you want to show actions.
Align	`left` `right`	Choose if you want to show the actions on the left or right side.

Behavior

Height

As content is injected into the dialog, the dialog grows vertically to accommodate the information passed to it.

Content overflow

When content exceeds the vertical space, it overflows and becomes scrollable.

<!--The trigger-->
<sl-button id="open-button" fill="solid" variant="primary">Open dialog</sl-button>

<!--The dialog-->
<sl-dialog id="dialog-example">
  <span slot="title">Dialog title</span>
  Dolore nulla ad magna nostrud cillum...
  <sl-button slot="actions" sl-dialog-close autofocus>Close</sl-button>
</sl-dialog>

<!--Event binding-->
<script>
  const openBtn = document.querySelector("#open-button");
  const dialogExample = document.querySelector("#dialog-example");

  openBtn.addEventListener("click", () => {
    if (dialogExample) {
      dialogExample.showModal();
    }
  })
</script>

Name	Attribute	Type	Default	Description
`closeButton`	`close-button`	`boolean \| undefined`		Determines whether a close button should be shown in the top right corner.
`dialogRole`	`dialog-role`	`'dialog' \| 'alertdialog'`	`'dialog'`	The role for the dialog element.
`disableCancel`	`disable-cancel`	`boolean \| undefined`		Disables the ability to cancel the dialog by pressing the Escape key or clicking on the backdrop.

Methods

Name	Parameters	Return	Description
`renderHeader`	`title:subtitle:`	`TemplateResult`	Override this method to customize the header of the dialog. If you only want to customize the title, you can use the `title` and `subtitle` arguments and call `super.renderHeader('My title', 'My subtitle')` to render the default header. Beware when customizing the header: the `<dialog>` element is labelled by the element with ID `title`. If you override this method, make sure to include an element with ID `title` in the header. Only use this when extending the `Dialog` class. If you are using the `<sl-dialog>` custom element, use the slots.
`renderBody`		`TemplateResult`	Override this method to customize the body of the dialog. Only use this when extending the `Dialog` class. If you are using the `<sl-dialog>` custom element, use the slots.
`renderFooter`		`TemplateResult`	Override this method to customize the footer of the dialog. If you only want to add action buttons, see the `renderActions` method. Only use this when extending the `Dialog` class. If you are using the `<sl-dialog>` custom element, use the slots.
`renderActions`		`TemplateResult \| typeof nothing`	Override this method to customize the actions in the footer of the dialog. Only use this when extending the `Dialog` class. If you are using the `<sl-dialog>` custom element, use the slots.
`showModal`		`void`	Show the dialog as a modal, in the top layer, with a backdrop.
`close`		`void`	Close the dialog.

Events

Name	Event type	Description
`sl-cancel`	`SlCancelEvent`	Emits when the dialog has been cancelled. This happens when the user closes the dialog using the escape key or clicks on the backdrop.
`sl-close`	`SlCloseEvent`	Emits when the dialog has been closed.

Slots

Name	Description
`actions`	Area where action buttons are placed
`default`	Body content for the dialog
`footer`	Footer content for the dialog
`header`	Header content for the dialog
`header-buttons`	More space for buttons for the dialog's header
`title`	The title of the dialog
`subtitle`	The subtitle of the dialog

CSS Properties

Name	Description
`--sl-dialog-max-inline-size`	The maximum width of the dialog

CSS Parts

Name	Description
`dialog`	The dialog element
`header`	The dialog header
`titles`	The container of the title and subtitle
`header-bar`	The button bar in the header
`body`	The body of the dialog
`footer`	The dialog footer
`footer-bar`	The button bar in the footer

Keyboard interactions

Command	Description
Tab	Moves focus to the next tabbable element inside the dialog. If focus is on the last tabbable element, it wraps back to the first. When the dialog is opened, focus is trapped within the dialog.
Shift + Tab	Moves focus to the previous tabbable element inside the dialog. If focus is on the first, it wraps to the last. When the dialog is opened, focus is trapped within the dialog.
Escape (ESC)	Closes the dialog, but only when `disableCancel` is set to `false` (default)

WAI-ARIA

Attribute	Value	Description	User suppliedSpecifies whether the attribute is always set in the component (no) or it needs to be provided by the developer (yes)
`ariaLabelledby`	string	Defines the aria-label of the dialog, taken from the contents of the `title` slot.	no
`ariaDescribedby`	string	Describes the purpose of the dialog	yes
`ariaModal`	boolean	Defines the type of dialog; whether it is modal or not	no
`ariaRole`	`'dialog', 'alertdialog'`	Defines the type of dialog; set by the `role` property, default is `dialog`	no

Interactive example