Dialog

A dialog container

Demo

function openDemoDialog() { document.getElementById('demo').showModal(); } function closeDemoDialog() { document.getElementById('demo').close(); }

API

Tag

Name	Description
`<s-dialog>`	Custom Element, accepts a required `<div slot='header'>` for a Dialog title, required `<div slot='body'>` containing any HTML content, and optional `<div slot='footer'>` with cancel/confirm button(s).

Classes

Name	Description
`overflow-visible`	Applies `overflow: visible` to the content of the `s-dialog`. See Guidelines for more information.

Slots

Name	Required	Description
`header`		Header content
`body`		Body content
`footer`		Footer content. Footer can be dynamically displayed or hidden by adding or removing `class="hidden"` on `<div slot="footer">`

Attributes

Name	Value	Required	Description
`open`	Boolean attribute		If present, the Dialog will be opened. When the open attribute is not set, the Dialog won't be shown to the user. The imperative `showModal` and `close` methods can also do this. When the Dialog is opened, focus will be shifted to one of the following, in descending order of precedence: the first focusable element (if any) in the content area, the first focusable element in the footer, the first focusable element in the header, or the dismiss button.
`nodismiss`	Boolean attribute		When present, removes the Dialog's dismiss button. You must provide an alternative way to dismiss it!
`backgroundclose`	Boolean attribute		When present, the Dialog is closed when the user clicks outside the Dialog
`i18n`	string		A stringified JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Properties

Name	Value	Description
`open`	Boolean attribute	If present, the Dialog will be opened. When the open attribute is not set, the Dialog won't be shown to the user. The imperative `showModal` and `close` methods can also do this. When the Dialog is opened, focus will be shifted to one of the following, in descending order of precedence: the first focusable element (if any) in the content area, the first focusable element in the footer, the first focusable element in the header, or the dismiss button.
`noDismiss`	Boolean attribute	When present, removes the Dialog's dismiss button. You must provide an alternative way to dismiss it!
`backgroundClose`	Boolean attribute	When present, the Dialog is closed when the user clicks outside the Dialog
`i18n`	object	A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Methods

Name Value Required Description

Name	Value	Required	Description
`showModal()`			Calling this method will open the Dialog. Calling this on an already open Dialog will do nothing. This method's name comes from the interface for HTMLDialogElement.
`close([returnValue])`			Calling this method will close the Dialog and set the Dialog's `returnValue` property to `returnValue`. This method does not match the interface for HTMLDialogElement because we allow `returnValue` to be of any type, not just DOMString. Be aware that closing the Dialog does not affect its content. If, for example, your Dialog has a form, anything the user may have entered will still be in the form. Your application must manage this content. If closing the Dialog should clear the form, your app will need to clear it.

showModal()

Calling this method will open the Dialog. Calling this on an already open Dialog will do nothing. This method's name comes from the interface for HTMLDialogElement.

close([returnValue])

Calling this method will close the Dialog and set the Dialog's returnValue property to returnValue. This method does not match the interface for HTMLDialogElement because we allow returnValue to be of any type, not just DOMString.

Be aware that closing the Dialog does not affect its content. If, for example, your Dialog has a form, anything the user may have entered will still be in the form. Your application must manage this content. If closing the Dialog should clear the form, your app will need to clear it.

Events

Name	Detail	Description
`s-dismiss`	The closed Dialog's `id` and `returnValue`	Fires after the Dialog was closed, which happens when the user presses the Escape key or clicks the dismiss button or when the application calls `close()`. There is no "open" event because the application manages if and when the Dialog gets opened.

Demo

Opening the demo dialog

Change the Boolean in open={false} to true.

API

Tag

Name	Description
`<SDialog>`	Accepts a required `<div slot='header'>` for a Dialog title, required `<div slot='body'>` containing any HTML content, and optional `<div slot='footer'>` with cancel/confirm button(s).

Classes

Name	Description
`overflow-visible`	Applies `overflow: visible` to the content of the `s-dialog`. See Guidelines for more information.

Slots

Name	Required	Description
`header`		Header content
`body`		Body content
`footer`		Footer content. Footer can be dynamically displayed or hidden by adding or removing `class="hidden"` on `<div slot="footer">`

Props

Name	Value	Required	Description
`open`	Boolean attribute		If present, the Dialog will be opened. When the open attribute is not set, the Dialog won't be shown to the user. When the Dialog is opened, focus will be shifted to one of the following, in descending order of precedence: the first focusable element (if any) in the content area, the first focusable element in the footer, the first focusable element in the header, or the dismiss button.
`noDismiss`	Boolean attribute		When present, removes the Dialog's dismiss button. You must provide an alternative way to dismiss it!
`backgroundClose`	Boolean attribute		When present, the Dialog is closed when the user clicks outside the Dialog
`i18n`	object		A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.
`onS-dismiss`	Function		Handles the `s-dismiss`event that fires after the Dialog was closed, which happens when the user presses the Escape key or clicks the dismiss button. There is no "open" event because the application manages if and when the Dialog gets opened. The closed Dialog's `id` and `returnValue` are available on `e.detail`.

Skylab React links

General information about using our React package

i18n Strings

ID	Description	Default value
`"dialog.ariaLabel.close"`	The aria-label used for the close button in the header.	Close

Guidelines

Accessibility

Give the dialog an aria-label or set aria-labelledby to the id of the header slot.

Dialog will default to role="dialog", but if your Dialog's content is urgent or really important (like an error) and requires some user input, then set role="alertdialog".

Opening the Dialog

It is highly recommended that you use a button or a link. Clicking any element can technically be used to trigger open, but buttons are more semantic and likely match user expectations. Occasionally application state rather than user interaction opens the Dialog.

Closing the dialog

Use of the overflow-visible class

The most common use case for this class is when <s-datepicker> is enclosed by a Dialog. Without the overflow-visible class, the <s-datepicker> will display incorrectly. When this class is used, the consuming app will be responsible for managing overflow of any content that extends beyond the Dialog's max-width and max-height.

Footer and buttons

If your Dialog requires buttons for a cancel and/or confirm use case, then put these buttons in a <div slot="footer"> with the primary button first. All buttons should be the standard size, not small or large. See Button Classes for details. This will ensure button placement meets design requirements.

Design

Design resources can be found on the Skylab design documentation site: skylab.avalara.com