Preview

Usage

The visible property is controlled via JavaScript:

<cs-button onclick="document.querySelector('#my-modal').visible = true">Open modal</cs-button>

<cs-modal id="my-modal" header="Confirm action">
  <p>Are you sure you want to proceed?</p>
  <cs-space-between slot="footer" direction="horizontal" size="xs">
    <cs-button variant="link" onclick="document.querySelector('#my-modal').visible = false">Cancel</cs-button>
    <cs-button variant="primary" onclick="document.querySelector('#my-modal').visible = false">Confirm</cs-button>
  </cs-space-between>
</cs-modal>

Properties

analytics-metadataModalProps.AnalyticsMetadata

Specifies additional analytics-related metadata.

• instanceIdentifier - A unique string that identifies this component instance in your application.
• flowType - Identifies the type of flow represented by the component.
• resourceType - Identifies the type of resource represented by the flow. Note: This API is currently experimental.

close-aria-labelstring default: 'Close'

Adds an aria-label to the close button, for accessibility.

disable-content-paddingsboolean default: false

Determines whether the modal content has padding. If true, removes the default padding from the content area.

get-modal-rootPortalProps['getContainer']

Use this property to specify a different dynamic modal root for the dialog. The function will be called when a user clicks on the trigger button.

heightnumber

Specifies the height of the modal. When provided, the modal content becomes scrollable if it exceeds the specified height. If the specified height exceeds available viewport space, the modal will use the maximum available space. To make sure the content is accessible, the component will apply a minimum height of 60px for the content area, plus the header height and the footer height.

modal-rootHTMLElement

Specifies the HTML element where the modal is rendered. If neither modalRoot or getModalRoot properties are provided, the modal will render to an element under document.body.

positionModalProps.Position default: 'center'

Controls the vertical positioning of the modal.

• center (default) - The modal is vertically centered in the viewport and re-centers when content height changes. Use for dialogs with static, predictable content.

• top - The modal anchors at fixed distance and grows downward as content expands. Use when the content changes dynamically to prevent disruptive vertical repositioning that can cause users to lose context.

remove-modal-rootPortalProps['removeContainer']

Use this property when getModalRoot is used to clean up the modal root element after a user closes the dialog. The function receives the return value of the most recent getModalRoot call as an argument.

sizeModalProps.Size default: 'medium'

Sets the width of the modal. max uses variable width up to the largest size allowed by the design guidelines. Other sizes have fixed widths: small (320px), medium (600px), large (820px), x-large (1024px), xx-large (1280px).

visiblebooleanrequired

Determines whether the modal is displayed on the screen. Modals are hidden by default. Set this property to true to show them.

widthnumber

Specifies the width of the modal. When provided, takes precedence over the size property. If the specified width exceeds available viewport space, the modal will use the maximum available space. The minimum width is 320px (equivalent to the small size).

Slots

default

Body of the modal.

footer

Specifies a footer for the modal. If empty, the footer isn't displayed.

header

Specifies a title for the modal. Although this can be empty, we suggest that you always provide a title.

Events

dismissCustomEvent<ModalProps.DismissDetail>

Called when a user closes the modal by using the close icon button, clicking outside of the modal, or pressing ESC. The event detail contains the reason, which can be any of the following: ['closeButton', 'overlay', 'keyboard'].