Dialog | Calcite Design System

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.

Sample

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

Component comparison

Dialogs, Popovers, and Tooltips may look similar, but each component is designed for a different level of content complexity and user interaction.

Dialog

This component

Best for critical workflows with large amounts of content.

Supports interactive elements, media, and other complex content, such as multi-step workflows.

Popover

Alternative

Best for non-critical workflows with small to medium amounts of content.

Supports simple interactive elements such as a Link or Button.

Tooltip

Alternative

Best for brief, supplemental content.

Supports text-only content with no interactive elements.

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.

Do ensure the modal property is used when the Dialog is intended to block page interaction

Avoid using the modal property when the Dialog does not contain critical or workflow-blocking content

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).

Do choose a placement that is appropriate for the content and context of the Dialog

Avoid using a modal Dialog in a placement other than "center", "top", or "cover" unless necessary

Content size and `width`

The width 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 width. 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.

Do use an appropriate width based on the content size and complexity

Avoid using too large or too small a Dialog for the content within

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.

Do use the built in heading and description properties

Do slot content in the default slot when possible

Avoid using the "header-content" slot unless required by a unique customization

Avoid using the "content" slot unless required by a unique customization

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.

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

Property	Attribute	Description	Type	Default
beforeClose		Specifies a function to run before the component closes.	`() => Promise<void>`
closeDisabled	close-disabled	When `true`, disables the component's close button.	`boolean`	`false`
description	description	Specifies the component's description.	`string`
dragEnabled	drag-enabled	When `true`, the component is draggable.	`boolean`	`false`
escapeDisabled	escape-disabled	When `true`, disables the default close on escape behavior. By default, an open dialog can be dismissed by pressing the Esc key.	`boolean`	`false`
focusTrapDisabled	focus-trap-disabled	When `true` and `modal` is `false`, prevents focus trapping.	`boolean`	`false`
focusTrapOptions		Specifies custom focus trap configuration on the component, where `"allowOutsideClick`" allows outside clicks, `"initialFocus"` enables initial focus, `"returnFocusOnDeactivate"` returns focus when not active, `"extraContainers"` specifies additional focusable elements external to the trap, such as 3rd-party components appending elements to the document body, and `"setReturnFocus"` customizes the element to which focus is returned when the trap is deactivated. Return `false` to prevent focus return, or `undefined` to use the default behavior (returning focus to the element focused before activation).	`Partial<FocusTrapOptions>`
fullscreenDisabled	fullscreen-disabled	When `true`, the component will not display at fullscreen, which may be desired in limited display areas, such as mobile devices.	`boolean`	`false`
heading	heading	Specifies the component's heading text.	`string`
headingLevel	heading-level	Specifies the heading level number of the component's `heading` for proper document structure, without affecting visual styling.	`HeadingLevel`
icon	icon	Specifies an icon to display.	`IconName`
iconFlipRtl	icon-flip-rtl	When `true` and the element direction is right-to-left (`"rtl"`), flips the component`s` icon`.	`boolean`	`false`
kind	kind	Specifies the component's kind, which determines the top border styling.	`Extract<"brand" \| "danger" \| "info" \| "success" \| "warning", Kind>`
loading	loading	When `true`, a busy indicator is displayed.	`boolean`	`false`
menuOpen	menu-open	When `true`, the action menu items in the `header-menu-actions` slot are open.	`boolean`	`false`
messageOverrides		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
modal	modal	When `true`, displays a scrim blocking interaction underneath the component.	`boolean`	`false`
open	open	When `true`, displays and positions the component.	`boolean`	`false`
outsideCloseDisabled	outside-close-disabled	When `true` and `modal` is `true`, disables the closing of the component when clicked outside.	`boolean`	`false`
overlayPositioning	overlay-positioning	Specifies the type of positioning to use for overlaid content, where: `"absolute"` works for most cases - positioning the component inside of overflowing parent containers, which affects the container's layout, and `"fixed"` is used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.	`OverlayPositioning`	`"absolute"`
placement	placement	Specifies the component's placement.	`DialogPlacement`	`"center"`
resizable	resizable	When `true`, the component is resizable.	`boolean`	`false`
scale	scale	Specifies the size of the component.	`Scale`	`"m"`
topLayerDisabled	top-layer-disabled	When `true` and the component is `open`, disables top layer placement. Only set this if you need complex z-index control or if top layer placement causes conflicts with third-party components.	`boolean`	`false`
width	width	Specifies the component's width.	`Extract<Width, Scale>`
widthScale	width-scale	deprecatedin v3.0.0, removal target v6.0.0 - Use the `width` property instead. Specifies the component's width.	`Scale`	`"m"`

Slots

Name	Description
default (unnamed)	A slot for adding content.
custom-content	A slot for displaying custom content. Will prevent the rendering of any default component UI, except for `box-shadow` and `corner-radius`.
action-bar	A slot for adding a `calcite-action-bar` to the component.
alerts	A slot for adding `calcite-alert`s to the component.
content-bottom	A slot for adding content below the unnamed (default) slot and - if populated - the `footer` slot.
content-top	A slot for adding content above the unnamed (default) slot and - if populated - below the `action-bar` slot.
header-actions-start	A slot for adding actions or content to the starting side of the component's header.
header-actions-end	A slot for adding actions or content to the ending side of the component's header.
header-content	A slot for adding custom content to the component's header.
header-menu-actions	A slot for adding an overflow menu with actions inside a `calcite-dropdown`.
heading	A slot for adding content to the heading area of the default header. Takes precedence over the `heading` property.
description	A slot for adding content to the description area of the default header. Takes precedence over the `description` property.
fab	A slot for adding a `calcite-fab` (floating action button) to perform an action.
footer	A slot for adding custom content to the component's footer. Should not be used with the `footer-start` or `footer-end` slots.
footer-end	A slot for adding a trailing footer custom content. Should not be used with the `footer` slot.
footer-start	A slot for adding a leading footer custom content. Should not be used with the `footer` slot.

Styles

Name	Description
--calcite-dialog-scrim-background-color	Specifies the background color of the component's scrim.
--calcite-dialog-size-x	When `placement` is `"cover"`, specifies the component's width, using `px`, `em`, `rem`, `vw`, or `%`. Does not exceed the viewport's width.
--calcite-dialog-min-size-x	Specifies the component's minimum width, using `px`, `em`, `rem`, `vw`, or `%`.
--calcite-dialog-max-size-x	Specifies the component's maximum width, using `px`, `em`, `rem`, `vw`, or `%`.
--calcite-dialog-size-y	When `placement` is `"cover"`, specifies the component's height, using `px`, `em`, `rem`, `vh`, or `%`. Does not exceed the viewport's height.
--calcite-dialog-min-size-y	Specifies the component's minimum height, using `px`, `em`, `rem`, `vh`, or `%`.
--calcite-dialog-max-size-y	Specifies the component's maximum height, using `px`, `em`, `rem`, `vh`, or `%`.
--calcite-dialog-content-space	Specifies the padding of the component's content.
--calcite-dialog-content-top-space	Specifies the padding of the component's `content-top` slot.
--calcite-dialog-content-bottom-space	Specifies the padding of the component's `content-bottom` slot.
--calcite-dialog-footer-space	Specifies the padding of the component's footer.
--calcite-dialog-border-color	Specifies the component's border color.
--calcite-dialog-offset-x	Specifies the component's horizontal offset.
--calcite-dialog-offset-y	Specifies the component's vertical offset.
--calcite-dialog-background-color	Specifies the component's background color.
--calcite-dialog-icon-color	Specifies the color of the component's icon.
--calcite-dialog-accent-color	When `kind` is specified, specifies the component's accent color.
--calcite-dialog-corner-radius	Specifies the component's corner radius.
--calcite-dialog-heading-text-color	Specifies the text color of the component's `heading`.
--calcite-dialog-description-text-color	Specifies the text color of the component's `description`.
--calcite-dialog-header-background-color	Specifies the background color of the component's header.
--calcite-dialog-header-action-background-color	Specifies the background color of the component's `closable`, `collapsible`, and slotted `header-menu-actions` `calcite-action`s.
--calcite-dialog-header-action-background-color-hover	Specifies the background color of the component's `closable`, `collapsible`, and slotted `header-menu-actions` `calcite-action`s when hovered.
--calcite-dialog-header-action-background-color-press	Specifies the background color of the component's `closable`, `collapsible`, and slotted `header-menu-actions` `calcite-action`s when pressed.
--calcite-dialog-header-action-text-color	Specifies the text color of the component's `closable`, `collapsible`, and slotted `header-menu-actions` `calcite-action`s.
--calcite-dialog-header-action-text-color-press	Specifies the text color of the component's `closable`, `collapsible`, and slotted `header-menu-actions` `calcite-action`s when pressed or hovered.
--calcite-dialog-footer-background-color	Specifies the background color of the component's footer.
--calcite-dialog-space	Specifies the padding of the component's `unnamed (default)` slot.
--calcite-dialog-header-content-space	Specifies the padding of the component's `header-content` slot.
--calcite-dialog-action-menu-border-color	Specifies the border color of the component's internally rendered `calcite-popover`, which is rendered within a `calcite-action` menu when slotted `calcite-action`s are present in the `header-actions-end` slot. Applies to any slotted `calcite-popover`s.

Events

Name	Description	Behavior
calciteDialogBeforeClose	Fires when the component is requested to be closed and before the closing transition begins.	bubblescomposed
calciteDialogBeforeOpen	Fires when the component is added to the DOM but not rendered, and before the opening transition begins.	bubblescomposed
calciteDialogClose	Fires when the component is closed and animation is complete.	bubblescomposed
calciteDialogOpen	Fires when the component is opened and animation is complete.	bubblescomposed
calciteDialogScroll	Fires when the component's content is scrolled.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
scrollContentTo	Scrolls the component's content to a specified set of coordinates.	`scrollContentTo(options?: ScrollToOptions): Promise<void>`
setFocus	Sets focus on the component's "close" button (the first focusable item).	`setFocus(options?: FocusOptions): Promise<void>`
updateFocusTrapElements	Updates the element(s) that are included in the focus-trap of the component.	`updateFocusTrapElements(extraContainers?: FocusTrapOptions["extraContainers"]): Promise<void>`
updateSize	Updates the component's size by setting its inline and/or block dimensions. Use this method to programmatically override the component's width (inline) and/or height (block). Pass `null` to clear the override and revert to the default or CSS variable size.	`updateSize(size: { inline?: number \| null; block?: number \| null; }): Promise<void>`