Modal
Calcite Modals are floating containers that can house simple messages or custom interfaces that are triggered contextually.
Overview
Modals are designed for interactions when the main interface can't contain descriptions or workflows within a given space. Modals have a scrim and lock the user into directly interacting with it. This can be useful when the user needs to perform an action or function to continue.
Modals should not be relied upon for primary workflows, and should be used sparingly.
Usage
- Contextual workflows or messaging
- Focused tasks
- Error messaging
- Onboarding
Sample
Accessibility
Keyboard navigation
Key | Function |
---|---|
Tab | Move focus to next item. If the current focus is the last item, the focus will cycle to the first item |
Tab and Shift | Move focus to previous item. If the current focus is the first item, the focus will cycle to the last item |
Esc | Closes the modal |
API reference
Properties
Property | Attribute | Description | Type | Values |
---|---|---|---|---|
active | active | When true, the `calcite-modal` is active. | true false | |
backgroundColor | background-color | Sets the background color of `calcite-modal` content. | grey white (default) | |
beforeClose | Passes a function to run before the `calcite-modal` closes. | (el: HTMLElement) => Promise<void> | ||
color | color | Adds a color bar to the top of `calcite-modal` for visual impact. Use color to add importance to destructive or workflow dialogs. | blue red | |
disableCloseButton | disable-close-button | When true, disables the close button within the `calcite-modal`. | true false | |
disableEscape | disable-escape | When true, disables the default close on escape behavior. | true false | |
disableOutsideClose | disable-outside-close | When true, disables the closing of the `calcite-modal` when clicked outside. | true false | |
docked | docked | When true, prevents the `calcite-modal` from expanding to the entire screen on mobile devices. | true false | |
fullscreen | fullscreen | Set the `calcite-modal` to always be fullscreen (overrides width). | true false | |
intlClose | intl-close | Accessible label for the close button. | TEXT.close (default) | |
noPadding | no-padding | When true, disables spacing to the content area slot. | true false | |
scale | scale | Specify the scale of `calcite-modal`. | l m (default) s | |
width | width | Set the width of the `calcite-modal`. Can use scale sizes or pass a number (displays in pixels). | l m (default) s |
Events
Name | Description | Detail |
---|---|---|
calciteModalClose | Emits when `calcite-modal` finishes the close animation. | any |
calciteModalOpen | Emits when `calcite-modal` finishes the open animation. | any |
Methods
Name | Description | Signature | Returns |
---|---|---|---|
focusElement | Focus the first interactive element. | focusElement(el?: HTMLElement) => Promise<void> | Promise<void> |
scrollContent | Set the scroll top of the `calcite-modal` content. | scrollContent(top?: number, left?: number) => Promise<void> | Promise<void> |
setFocus | Sets focus on the component. By default, tries to focus on focusable content. If there is none, it will focus on the close button. To focus on the close button, use the `close-button` focus ID. | setFocus(focusId?: "close-button") => Promise<void> | Promise<void> |
Slots
Name | Description |
---|---|
back | A slot for adding a back button. |
content | A slot for adding `calcite-modal` content. |
header | A slot for adding a `calcite-modal` header. |
primary | A slot for adding a primary button. |
secondary | A slot for adding a secondary button. |
Styles
Name | Description | CSS Variable |
---|---|---|
--calcite-modal-content-text | The `calcite-modal` content font size. | --calcite-modal-content-text |
--calcite-modal-padding | The top/bottom padding around items in the `calcite-modal`. | --calcite-modal-padding |
--calcite-modal-padding-large | The left/right padding around items in the `calcite-modal`. | --calcite-modal-padding-large |
--calcite-modal-title-text | The `calcite-modal` title font size. | --calcite-modal-title-text |
--calcite-scrim-background | The semi-transparent background color behind the `calcite-modal`. | --calcite-scrim-background |