Overview
Usage
- Contextual workflows or messaging
- Focused tasks
- Error messaging
- Onboarding
Sample
<calcite-modal aria-labelledby="modal-title" id="example-modal">
<div slot="header" id="modal-title">
Add a group
</div>
<div slot="content">
<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="pencil" width="full">
<div slot="message">You can edit this choice later on, in Settings.</div>
</calcite-notice>
</div>
<calcite-button slot="back" kind="neutral" width="full">
Back
</calcite-button>
<calcite-button slot="secondary" width="full" appearance="outline">
Cancel
</calcite-button>
<calcite-button slot="primary" width="full">
Save
</calcite-button>
</calcite-modal>
<calcite-button id="example-button">Open modal</calcite-button>
Accessibility
Focus order
The Modal'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 Modal will receive keyboard focus, such as the component's close button (default).
Keyboard focus
It is strongly recommended to have focusable elements cycle through Modal where focus
is false
(default) to support assistive technology users. The expected behavior for assistive technologies is while the component is open
only the contents and focusable elements are accessible.
Keyboard navigation
Key | Function |
---|---|
Tab | Moves focus to next focusable element. If the current focus is the last element and focus is false , focus will cycle to the first element. |
Tab and Shift | Moves focus to previous focusable element. If the current focus is the first element and focus is false , focus will cycle to the last element. |
Esc | If escape is false , closes the component. |
API reference
Properties
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
beforeClose | Passes a function to run before the component closes. | (el: HTMLCalciteModalElement) => Promise<void> | ||
closeButtonDisabled | close-button-disabled | When true , disables the component's close button. | boolean | false |
docked | docked | When true , prevents the component from expanding to the entire screen on mobile devices. | boolean | false |
escapeDisabled | escape-disabled | When true , disables the default close on escape behavior. | boolean | false |
focusTrapDisabled | focus-trap-disabled | When true , 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, 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>;
} | ||
fullscreen | fullscreen | Sets the component to always be fullscreen. Overrides widthScale and --calcite-modal-width / --calcite-modal-height . | boolean | false |
kind | kind | Specifies the kind of the component, which will apply to top border. | "brand" | "danger" | "info" | "success" | "warning" | |
messageOverrides | Use this property to override individual strings used by the component. | { close?: string; } | ||
open | open | When true , displays and positions the component. | boolean | false |
outsideCloseDisabled | outside-close-disabled | When true , disables the closing of the component when clicked outside. | boolean | false |
scale | scale | Specifies the size of the component. | "l" | "m" | "s" | "m" |
widthScale | width-scale | Specifies the width of the component. | "l" | "m" | "s" | "m" |
Slots
Name | Description |
---|---|
header | A slot for adding header text. |
content | A slot for adding the component's content. |
content-top | A slot for adding content to the component's sticky header, where content remains at the top of the component when scrolling up and down. |
content-bottom | A slot for adding content to the component's sticky footer, where content remains at the bottom of the component when scrolling up and down. |
primary | A slot for adding a primary button. |
secondary | A slot for adding a secondary button. |
back | A slot for adding a back button. |
Styles
Name | Description |
---|---|
--calcite-modal-content-background | Specifies the background color of content placed in the component's "content" slot. |
--calcite-modal-content-padding | Specifies the padding of the component's "content" slot. |
--calcite-modal-scrim-background | Specifies the background color of the component's scrim. |
--calcite-modal-width | Specifies the width of the component, using px , em , rem , vw , or % . Will never exceed the width of the viewport. Will not apply if fullscreen if set. |
--calcite-modal-height | Specifies the height of the component, using px , em , rem , vh , or % . Will never exceed the height of the viewport. Will not apply if fullscreen if set. |
Events
Name | Description | Behavior |
---|---|---|
calciteModalBeforeClose | Fires when the component is requested to be closed and before the closing transition begins. | |
calciteModalBeforeOpen | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | |
calciteModalClose | Fires when the component is closed and animation is complete. | |
calciteModalOpen | Fires when the component is open and animation is complete. |
Methods
Name | Description | Signature |
---|---|---|
componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<void> |
scrollContent | Sets the scroll top of the component's content. | scrollContent(top?: number, left?: number): Promise<void> |
setFocus | Sets focus on the component's "close" button (the first focusable item). | setFocus(): Promise<void> |
updateFocusTrapElements | Updates the element(s) that are included in the focus-trap of the component. | updateFocusTrapElements(extraContainers?:
FocusTrapOptions["extraContainers"]): Promise<void> |