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

Show code snippetCopy code snippet
Edit sample on Codepen
v1.0.0-beta.83
Toggle preview themeToggle preview direction

Accessibility

Keyboard navigation

KeyFunction
TabMove focus to next item. If the current focus is the last item, the focus will cycle to the first item
Tab and ShiftMove focus to previous item. If the current focus is the first item, the focus will cycle to the last item
EscCloses the modal

API reference

calcite-modal
v1.0.0-beta.83

Properties

PropertyAttributeDescriptionTypeValues
activeactive

When true, the `calcite-modal` is active.

booleanA boolean property should be present, or not
truefalse
backgroundColorbackground-color

Sets the background color of `calcite-modal` content.

typedChoose from a set of typed values
greywhite (default)
beforeClose

Passes a function to run before the `calcite-modal` closes.

optional
functionA function
(el: HTMLElement) => Promise<void>
colorcolor

Adds a color bar to the top of `calcite-modal` for visual impact. Use color to add importance to destructive or workflow dialogs.

optional
typedChoose from a set of typed values
bluered
disableCloseButtondisable-close-button

When true, disables the close button within the `calcite-modal`.

booleanA boolean property should be present, or not
truefalse
disableEscapedisable-escape

When true, disables the default close on escape behavior.

booleanA boolean property should be present, or not
truefalse
disableOutsideClosedisable-outside-close

When true, disables the closing of the `calcite-modal` when clicked outside.

booleanA boolean property should be present, or not
truefalse
dockeddocked

When true, prevents the `calcite-modal` from expanding to the entire screen on mobile devices.

booleanA boolean property should be present, or not
truefalse
fullscreenfullscreen

Set the `calcite-modal` to always be fullscreen (overrides width).

booleanA boolean property should be present, or not
truefalse
intlCloseintl-close

Accessible label for the close button.

stringA custom string
TEXT.close (default)
noPaddingno-padding

When true, disables spacing to the content area slot.

booleanA boolean property should be present, or not
truefalse
scalescale

Specify the scale of `calcite-modal`.

typedChoose from a set of typed values
lm (default)s
widthwidth

Set the width of the `calcite-modal`. Can use scale sizes or pass a number (displays in pixels).

typedChoose from a set of typed values
lm (default)s

Events

NameDescriptionDetail
calciteModalClose

Emits when `calcite-modal` finishes the close animation.

bubblescomposedcancelable
any
calciteModalOpen

Emits when `calcite-modal` finishes the open animation.

bubblescomposedcancelable
any

Methods

NameDescriptionSignatureReturns
focusElement
deprecateduse `setFocus` instead.

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

NameDescription
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

NameDescriptionCSS 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

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