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.

UsageCodeAccessibility

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

ItemNameDescriptionOptional
1OverlayObscures the page content behind the panelNo
2PanelContains the header, subheader, panel content and actionsNo
3HeaderAn area to display content at the top of the panel (e.g. title)Yes
4SubheaderAn area to display the description of the titleYes
5Close buttonIcon button for closing the dialogYes
6ContentAn area to display any contentYes

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.

ItemOptionsDescription
Devicedesktop mobileSelect the device for your prototype to ensure an optimal layout.
Sizesm md (default) lg xlThe dialog come in four sizes: small, medium (default), large and extra large, providing flexibility to align with your design requirements.
Close IconbooleanChoose if you want to show a close button.
Header Ordertitle subtitleChoose if you want to start with the title or subtitle.
ContentbooleanChoose if you want to show content (slot component).
Slot Component.slotSelect your own component to display within the dialog component.
ActionsbooleanChoose if you want to show actions.
Alignleft rightChoose 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.

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>

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

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

Migrating to SLDS Dialog

When using the dialog in an existing application, and more importantly, using existing code in the contents of the dialog there are a few caveats. Please read our overlay guidelines on possible issues that can occur and how to prevent or solve them.

API

Component has a range of properties to define the experience in different use cases.

Properties

NameAttributeTypeDefaultDescription
closeButtonclose-buttonboolean | undefinedDetermines whether a close button should be shown in the top right corner.
dialogRoledialog-role'dialog' | 'alertdialog''dialog'The role for the dialog element.
disableCanceldisable-cancelboolean | undefinedDisables the ability to cancel the dialog by pressing the Escape key
or clicking on the backdrop.

Methods

NameParametersReturnDescription
showModalvoidShow the dialog as a modal, in the top layer, with a backdrop.
closevoidClose the dialog.

Events

NameEvent typeDescription
sl-cancelSlCancelEventEmits when the cancel has been cancelled. This happens when the user closes
the dialog using the escape key or clicks on the backdrop.
sl-closeSlCloseEventEmits when the dialog has been closed.

Slots

NameDescription
actionsArea where action buttons are placed
defaultBody content for the dialog
footerFooter content for the dialog
headerHeader content for the dialog
header-buttonsMore space for buttons for the dialog's header
titleThe title of the dialog
subtitleThe subtitle of the dialog

CSS Properties

NameDescription
--sl-dialog-max-inline-sizeThe maximum width of the dialog

Keyboard interactions

CommandDescription
TabMoves focus to the next tabbable element inside the dialog. If focus is on the last tabbable element, it wraps back to the first.
Shift + TabMoves focus to the previous tabbable element inside the dialog. If focus is on the first, it wraps to the last.
Escape (ESC)Closes the dialog, but only when disableCancel is set to false (default)

WAI-ARIA

AttributeValueDescriptionUser suppliedSpecifies whether the attribute is always set in the component (no) or it needs to be provided by the developer (yes)
ariaLabelledbystringDefines the aria-label of the dialog, taken from the contents of the title slot.no
ariaDescribedbystringDescribes the purpose of the dialogyes
ariaModalbooleanDefines the type of dialog; whether it is modal or notno
ariaRole'dialog', 'alertdialog'Defines the type of dialog; set by the role property, default is dialogno
Interactive example