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

6 samples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<calcite-dialog open modal heading="Add a group" id="example-dialog">
    <calcite-label>
        Group name
        <calcite-input value="City of Acme Surveying Crews" placeholder="Enter a descriptive title"></calcite-input>
    </calcite-label>
    <calcite-label>
        Choose default user role
        <calcite-tile-select-group>
            <calcite-tile-select checked input-enabled input-alignment="end" icon="rangefinder" heading="Field operator"
                description="This role allows users in the field to create new Reports, and view and edit existing Reports and Attachments">
            </calcite-tile-select>
            <calcite-tile-select input-enabled input-alignment="end" icon="knowledge-graph-dashboard"
                heading="Office coordinator"
                description="This role allows teammates on-base to view, duplicate, and create meaningful insights from Reports">
            </calcite-tile-select>
        </calcite-tile-select-group>
    </calcite-label>
    <calcite-notice open icon width="full">
        <div slot="message">You can edit this choice later on, in Settings.</div>
    </calcite-notice>
    <calcite-button slot="footer-start" kind="neutral">
        Back
    </calcite-button>
    <calcite-button slot="footer-end" appearance="outline">
        Cancel
    </calcite-button>
    <calcite-button slot="footer-end">
        Save
    </calcite-button>
</calcite-dialog>
<calcite-button id="example-button">Open dialog</calcite-button>
v3.0.3

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.

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.

Keyboard navigation

KeyFunction
TabMoves focus to next focusable element. If the current focus is the last element, focus will cycle to the first element.
Tab and ShiftMoves focus to previous focusable element. If the current focus is the first element, focus will cycle to the last element.
Arrow upWhen dragEnabled is true and the component is in focus, moves the component up.
Arrow downWhen dragEnabled is true and the component is in focus, moves the component down.
Arrow leftWhen dragEnabled is true and the component is in focus, moves the component left.
Arrow rightWhen dragEnabled is true and the component is in focus, moves the component right.
Shift and Arrow upWhen resizable is true and the component is in focus, decreases the component's height.
Shift and Arrow downWhen resizable is true and the component is in focus, increases the component's height.
Shift and Arrow leftWhen resizable is true and the component is in focus, decreases the component's width.
Shift and Arrow rightWhen resizable is true and the component is in focus, increases the component's width.
EscCloses the component.

API reference

Properties

PropertyAttributeDescriptionTypeDefault
beforeClosePasses a function to run before the component closes.() => Promise<void>
closeDisabledclose-disabledWhen true, disables the component's close button.booleanfalse
descriptiondescriptionA description for the component.string
dragEnableddrag-enabledWhen true, the component is draggable.booleanfalse
escapeDisabledescape-disabledWhen true, disables the default close on escape behavior. By default, an open dialog can be dismissed by pressing the Esc key.booleanfalse
focusTrapDisabledfocus-trap-disabledWhen true and modal is false, prevents focus trapping.booleanfalse
focusTrapOptionsSpecifies custom focus trap configuration on the component, where "allowOutsideClick" allows outside clicks, "initialFocus" enables initial focus, "returnFocusOnDeactivate" returns focus when not active, and "extraContainers" specifies additional focusable elements external to the trap (e.g., 3rd-party components appending elements to the document body).{ initialFocus?: FocusTargetOrFalse | (() => void); returnFocusOnDeactivate?: boolean; allowOutsideClick?: boolean | MouseEventToBoolean; extraContainers?: string | HTMLElement | SVGElement | Array<string | HTMLElement | SVGElement>; }
headingheadingThe component header text.string
headingLevelheading-levelSpecifies the heading level of the component's heading for proper document structure, without affecting visual styling.1 | 2 | 3 | 4 | 5 | 6
kindkindSpecifies the kind of the component, which will style the top border."brand" | "danger" | "info" | "success" | "warning"
loadingloadingWhen true, a busy indicator is displayed.booleanfalse
menuOpenmenu-openWhen true, the action menu items in the header-menu-actions slot are open.booleanfalse
messageOverridesUse this property to override individual strings used by the component.{ close?: string; resizeEnabled?: string; dragEnabled?: string; }
modalmodalWhen true, displays a scrim blocking interaction underneath the component.booleanfalse
openopenWhen true, displays and positions the component.booleanfalse
outsideCloseDisabledoutside-close-disabledWhen true, disables the closing of the component when clicked outside.booleanfalse
overlayPositioningoverlay-positioningDetermines the type of positioning to use for the overlaid content. Using "absolute" will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. "fixed" should be used to escape an overflowing parent container, or when the reference element's position CSS property is "fixed"."absolute" | "fixed""absolute"
placementplacementSpecifies the placement of the dialog."bottom" | "bottom-end" | "bottom-start" | "center" | "cover" | "top" | "top-end" | "top-start""center"
resizableresizableWhen true, the component is resizable.booleanfalse
scalescaleSpecifies the size of the component."l" | "m" | "s""m"
widthwidthSpecifies the width of the component."l" | "m" | "s"
widthScalewidth-scale
deprecatedUse the width property instead.
Specifies the width of the component.
"l" | "m" | "s""m"

Slots

NameDescription
default (unnamed)A slot for adding content.
content
deprecated Use custom-content slot instead.
custom-contentA slot for displaying custom content. Will prevent the rendering of any default Dialog UI, except for box-shadow and corner-radius.
action-barA slot for adding a calcite-action-bar to the component.
alertsA slot for adding calcite-alerts to the component.
content-bottomA slot for adding content below the unnamed (default) slot and - if populated - the footer slot.
content-topA slot for adding content above the unnamed (default) slot and - if populated - below the action-bar slot.
header-actions-startA slot for adding actions or content to the starting side of the component's header.
header-actions-endA slot for adding actions or content to the ending side of the component's header.
header-contentA slot for adding custom content to the component's header.
header-menu-actionsA slot for adding an overflow menu with actions inside a calcite-dropdown.
fabA slot for adding a calcite-fab (floating action button) to perform an action.

Styles

NameDescription
--calcite-dialog-scrim-background-colorSpecifies the background color of the component's scrim.
--calcite-dialog-size-xSpecifies the width of the component, using px, em, rem, vw, or %. Does not exceed the viewport's width - applies when placement="cover" is set.
--calcite-dialog-min-size-xSpecifies the minimum width of the component, using px, em, rem, vw, or %.
--calcite-dialog-max-size-xSpecifies the maximum width of the component, using px, em, rem, vw, or %.
--calcite-dialog-size-ySpecifies the height of the component, using px, em, rem, vh, or %. Does not exceed the viewport's height - applies when placement="cover" is set.
--calcite-dialog-min-size-ySpecifies the minimum height of the component, using px, em, rem, vh, or %.
--calcite-dialog-max-size-ySpecifies the maximum height of the component, using px, em, rem, vh, or %.
--calcite-dialog-content-spaceSpecifies the padding of the component's content.
--calcite-dialog-border-colorSpecifies the component's border color.
--calcite-dialog-offset-xSpecifies the horizontal offset of the component.
--calcite-dialog-offset-ySpecifies the vertical offset of the component.
--calcite-dialog-background-colorSpecifies the background color of the component.

Events

NameDescriptionBehavior
calciteDialogBeforeCloseFires when the component is requested to be closed and before the closing transition begins.bubblescomposed
calciteDialogBeforeOpenFires when the component is added to the DOM but not rendered, and before the opening transition begins.bubblescomposed
calciteDialogCloseFires when the component is closed and animation is complete.bubblescomposed
calciteDialogOpenFires when the component is open and animation is complete.bubblescomposed
calciteDialogScrollFires when the content is scrolled.bubblescomposed

Methods

NameDescriptionSignature
componentOnReadyCreate a promise that resolves once component is fully loaded.componentOnReady(): Promise<void>
scrollContentToScrolls the component's content to a specified set of coordinates.scrollContentTo(options?: ScrollToOptions): Promise<void>
setFocusSets focus on the component's "close" button (the first focusable item).setFocus(): Promise<void>
updateFocusTrapElementsUpdates the element(s) that are included in the focus-trap of the component.updateFocusTrapElements(extraContainers?: FocusTrapOptions["extraContainers"]): Promise<void>

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close