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. | truefalse | |
| backgroundColor | background-color | Sets the background color of `calcite-modal` content. | greywhite (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. | bluered | |
| disableCloseButton | disable-close-button | When true, disables the close button within the `calcite-modal`. | truefalse | |
| disableEscape | disable-escape | When true, disables the default close on escape behavior. | truefalse | |
| disableOutsideClose | disable-outside-close | When true, disables the closing of the `calcite-modal` when clicked outside. | truefalse | |
| docked | docked | When true, prevents the `calcite-modal` from expanding to the entire screen on mobile devices. | truefalse | |
| fullscreen | fullscreen | Set the `calcite-modal` to always be fullscreen (overrides width). | truefalse | |
| intlClose | intl-close | Accessible label for the close button. | TEXT.close (default) | |
| noPadding | no-padding | When true, disables spacing to the content area slot. | truefalse | |
| scale | scale | Specify the scale of `calcite-modal`. | lm (default)s | |
| width | width | Set the width of the `calcite-modal`. Can use scale sizes or pass a number (displays in pixels). | lm (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 |