Dialog modal

Dialog modals are used to validate user decisions or to gain secondary information from the user.

1. Anatomy

Aria attributes

Value	Purpose
role = “dialog”	Identifies the component.
aria-modal = “true”	Tells assistive technologies that the windows underneath the current dialog are not available for interaction (inert).
aria-labelledby= “[id-of-the-title-h2]”	Gives the dialog an accessible name by referring to the element that provides the dialog title.
aria-desicribeby= “[id-of-the-description-paragraph]”	Gives further context about the dialog’s purpose. It is optional.

2. Configurations

2.1 Size (desktop only)

The size element only impacts the container’s width. It has:

small: 480px
medium (default): 648px
large: 720px
extra-large: 1024px
custom: your own width

The container’s height is set by setting the height of the content slot. Please take the header and the footer’s height into calculation when setting the content’s height.

For the responsiveness detail, please go to 5.0 Resilience & responsiveness.

See the more examples about how the content’s height impacts the containers’s height.

2.2 Alignment

Alignment only affects the header and the footer. It does NOT affect the content of the dialog. Your need to style the content layout yourself.

2.3 Footer buttons

Both desktop and mobile versions support maximum 3 buttons.

Desktop version:

The button layout of the desktop version changes based on modal’s alignment configuration.

Mobile version:

The buttons on the mobile version are always centered. It does not affect by the alignment configuration. However, users can choose whether to horizontally or vertically stack two buttons.

Mobile modals are always set to 100% width and 100% height of the viewport and behave like a full screen mobile sheet.

2.4 Background Image

Use background image property to add a background image. The image spans from top of the header to bottom of the footer. The divider will be hidden once the background image is enabled.

Please note, the background color of the Dialog modal is set to $color-background-primary and it cannot be changed.

Please either use an image suitable for both light and dark mode or have separate images for two mode.

2.5 Close on overlay click

Default=false; Clicking on the overlay closes the dialog by default. However in certain cases where you need the user to take an action without dismissing the dialog or tp prevent accidental closure, you can set the close on overlay click to false.

When set to false, the dialog will remain open even when the use clicks on the overlay area.

ESC key will close the dialog regardless of this configuration for accessibility reason.

3. Behavior

Action needs to take place to close a modal. Modal can be dismissed in one of the following ways:

1. Completing a task : When a task is completed, clicking the confirmation button in the footer will also close the modal. Occasionally, an action inside the content may close the dialog.

2. Clicking on the overlay: If closeOnOverlayClick is set to true (default is false, see sec 2.4), clicking on the overlay will close the dialog.

3. Pressing Esc key: Pressing ESC on the keyboard will close the dialog.

4. Keyboard experience

Modals need to trap the keyboard tab (and touch-assistive gestures on mobile) so that the content behind the overlay is not focusable till the dialog is open.

When the dialog appears on the screen, keyboard focus (whose control depends upon the dialog’s purpose) should be moved to the default focusable control inside the dialog. For dialogs that only provide a basic message, it could be an “OK” button. For dialogs containing a form it could be the first field in the form.
After the dialog is dismissed, keyboard focus should be moved back to where it was before it moved into the dialog. Otherwise the focus can be dropped to the beginning of the page.