Dialog

Dialogs are positioned, floating containers intended for presenting content or workflows requiring focus from a user.

Overview

Dialogs are designed for presenting focused interactions, tasks, or workflows to a user. They can be configured to suit a variety of use cases and interface needs, ranging from brief informational prompts to complex multi-step workflows.

Usage

• Focused workflows, tasks, or prompts
• Engaging users with onboarding or instructional content
• Presenting blocking or critical information to a user
• Interrupting a workflow to present a choice or provide guidance

Sample

Best practices

Some use cases of Dialog may take the form of page-blocking interactions - and should make use of the modal property - other use cases will be non-modal and allow the user to interact with the main application content while the Dialog is open.

It may be necessary or desirable to prevent a user from dismissing a Dialog, which can be accomplished by leveraging the calciteDialogBeforeClose event. Through the use of this event, it is possible to display a confirmation or warning to the user, which can be useful to avoid accidental dismissals of the Dialog during a complex or multi-step workflow.

Modal behavior

Dialogs are non-modal by default, allowing a user to interact with the main application content while the component is open. Dialogs can also be modal - and display a Scrim behind the component to prevent interaction with the main content.

If the Dialog is intended to provide a user with a critical piece of information, or to block interaction with the main application content, modal should be set to true. Generally, it is preferable to use modal if the user is presented with a complex or multi-step workflow. Conversely, if the Dialog is intended to provide a user with a non-critical piece of information, or to allow interaction with the main application content, modal should not be used.

Component placement

The placement property should be used to determine the position of the Dialog relative to the user's viewport. Generally, a modal Dialog should be placed in the center of the viewport with the "center" value.

Setting placement to "cover" will present the Dialog as a full-viewport overlay. This can be useful for intensive or complex workflows, or displays of interactive content or rich media. Invoking a Dialog with "cover" can be a helpful way to provide focus to a complex workflow - but ensure that it is not presented in a way that is unexpected or jarring to the user (such as invoking it without user interaction).

Content size and widthScale

The widthScale property should be used to determine the visual size of the Dialog presented to a user.

A user can infer a level of severity or complexity from the size of the component. Large amounts of content may be difficult to read or navigate if presented in a Dialog of too small a widthScale. Conversely, a Dialog with a small amount of content may feel sparse and empty if presented in too large of a Dialog.

Further customization can be achieved through the use of CSS Properties. These fine-grained controls should be used for specific use cases when the provided values do not satisfy a custom use case or need.

Content slots

While the vast majority of content should be slotted into the default slot, there may be occasions where you may wish to replace the entire Dialog content with a bespoke solution. In this case, the content slot can be used to provide the positioning and optional modal capabilities of Dialog, but without the structure and style of the default Dialog.

Accessibility

Focus order

The Dialog's focus will navigate content sequentially to preserve meaning and expected use in support of Success Criterion 2.4.3: Focus Order. For this reason the first element depicted visually in the Dialog will receive keyboard focus, such as the component's close button (default).

The Dialog will automatically receive and trap focus when opened, regardless of whether it is modal, and regardless of whether open is set programmatically or as a result of user action.

Forms mode

Screen readers will often switch to "Forms mode" when accessing form elements. When accessing Dialog via Forms mode with dragEnabled and/or resizable set to true, screen reader users can drag or resize the component respectively.

Keyboard navigation

Key	Function
Tab	Moves focus to next focusable element. If the current focus is the last element, focus will cycle to the first element.
Tab and Shift	Moves focus to previous focusable element. If the current focus is the first element, focus will cycle to the last element.
Arrow up	When dragEnabled is true and the component is in focus, moves the component up.
Arrow down	When dragEnabled is true and the component is in focus, moves the component down.
Arrow left	When dragEnabled is true and the component is in focus, moves the component left.
Arrow right	When dragEnabled is true and the component is in focus, moves the component right.
Shift and Arrow up	When resizable is true and the component is in focus, decreases the component's height.
Shift and Arrow down	When resizable is true and the component is in focus, increases the component's height.
Shift and Arrow left	When resizable is true and the component is in focus, decreases the component's width.
Shift and Arrow right	When resizable is true and the component is in focus, increases the component's width.
Esc	Closes the component.

API reference

Properties

Slots

Styles

Events

Methods