Modal

Displays content in an overlay. Use to create a distraction-free experience such as a confirmation dialog or a settings panel.

Anchor to propertiesProperties

Anchor to accessibilityLabel accessibilityLabel string: A label that describes the purpose of the modal. When set, it will be announced to users using assistive technologies and will provide them with more context.

This overrides the heading prop for screen readers.
Anchor to heading heading string: A title that describes the content of the Modal.
Anchor to hideOverlay hideOverlay () => void: Method to hide an overlay.
Anchor to padding padding "base" | "none" Default: 'base': Adjust the padding around the Modal content.

base: applies padding that is appropriate for the element.

none: removes all padding from the element. This can be useful when elements inside the Modal need to span to the edge of the Modal. For example, a full-width image. In this case, rely on Box with a padding of 'base' to bring back the desired padding for the rest of the content.
Anchor to showOverlay showOverlay () => void: Method to show an overlay.
Anchor to size size "small" | "small-100" | "base" | "large" | "large-100" Default: 'base': Adjust the size of the Modal.
Anchor to toggleOverlay toggleOverlay () => void: Method to toggle the visiblity of an overlay.

Anchor to eventsEvents

Learn more about registering events.

Anchor to afterhide afterhide <typeof tagName> | null
Anchor to aftershow aftershow <typeof tagName> | null
Anchor to hide hide <typeof tagName> | null
Anchor to show show <typeof tagName> | null

Anchor to slotsSlots

Anchor to children children HTMLElement: The content of the Modal.
Anchor to primary-action primary-action HTMLElement: The primary action to perform.

Only a Button with a variant of primary is allowed.
Anchor to secondary-actions secondary-actions HTMLElement: The secondary actions to perform.

Only Button elements with a variant of secondary or auto are allowed.

Code

<s-button commandFor="modal">Open</s-button>

<s-modal id="modal" heading="Details">

<s-paragraph>Displaying more details here.</s-paragraph>

<s-button slot="secondary-actions" commandFor="modal" command="--hide">

</s-button>

<s-button

slot="primary-action"

variant="primary"

commandFor="modal"

command="--hide"

Save

</s-button>

</s-modal>

</>

Preview

Examples

Code

jsx

<>
  <s-button commandFor="modal">Open</s-button>

  <s-modal id="modal" heading="Details">
    <s-paragraph>Displaying more details here.</s-paragraph>

    <s-button slot="secondary-actions" commandFor="modal" command="--hide">
      Close
    </s-button>
    <s-button
      slot="primary-action"
      variant="primary"
      commandFor="modal"
      command="--hide"
    >
      Save
    </s-button>
  </s-modal>
</>

html

<s-button commandFor="modal">Open</s-button>

<s-modal id="modal" heading="Details">
  <s-paragraph>Displaying more details here.</s-paragraph>

  <s-button slot="secondary-actions" commandFor="modal" command="--hide">
    Close
  </s-button>
  <s-button
    slot="primary-action"
    variant="primary"
    commandFor="modal"
    command="--hide"
  >
    Save
  </s-button>
</s-modal>

Anchor to usageUsage

Modals are closed by default and should be triggered by a button using the commandFor attribute. The button's commandFor value should match the modal's id.

Was this section helpful?

Anchor to useful-forUseful for

Focusing on a specific task or piece of information
Completing a flow that needs dedicated attention
Confirming a significant action before proceeding
Viewing information that's only temporarily relevant

Was this section helpful?

Anchor to best-practicesBest practices

Use for focused, specific tasks that require merchants to make a decision or acknowledge critical information
Include a prominent and clear call to action
Don't nest modals (avoid launching one modal from another)
Have concise and descriptive title and button text
Use thoughtfully and sparingly—don't create unnecessary interruptions
Use as a last resort for important decisions, not for contextual tools or actions that could happen on the page directly

Was this section helpful?

Anchor to content-guidelinesContent guidelines

Use 1-3 word titles in sentence case without punctuation
Keep body content to 1-2 short sentences
For destructive actions, explain the consequences
Use clear action verbs for buttons (e.g., "Delete", "Edit") instead of vague language like "Yes" or "OK"

Was this section helpful?

Anchor to examplesExamples

Component examples

Anchor to example-basic-usageBasic usage

Was this section helpful?

Basic modal

<s-button commandFor="info-modal" command="--show">

Show product info

</s-button>

<s-modal id="info-modal" heading="Product information">

<s-text>

This product is currently out of stock and cannot be ordered.

</s-text>

<s-button slot="secondary-actions" commandFor="info-modal" command="--hide">

</s-button>

</s-modal>

</>

Preview

Examples

Basic modal

Description

Simple modal with heading and basic content for displaying information. Click the button to open the modal.

jsx

<>
  <s-button commandFor="info-modal" command="--show">
    Show product info
  </s-button>

  <s-modal id="info-modal" heading="Product information">
    <s-text>
      This product is currently out of stock and cannot be ordered.
    </s-text>

    <s-button slot="secondary-actions" commandFor="info-modal" command="--hide">
      Close
    </s-button>
  </s-modal>
</>

html

<s-button commandFor="info-modal" command="--show">Show product info</s-button>

<s-modal id="info-modal" heading="Product information">
  <s-text>This product is currently out of stock and cannot be ordered.</s-text>

  <s-button slot="secondary-actions" commandFor="info-modal" command="--hide">
    Close
  </s-button>
</s-modal>

Modal with actions

Description

Modal with primary and secondary action buttons. Click the button to open the confirmation modal.

jsx

<s-stack gap="base">
  <s-button tone="critical" commandFor="delete-modal" command="--show">
    Delete product
  </s-button>

  <s-modal id="delete-modal" heading="Delete product?">
    <s-stack gap="base">
      <s-text>Are you sure you want to delete "Winter jacket"?</s-text>
      <s-text tone="caution">This action cannot be undone.</s-text>
    </s-stack>

    <s-button
      slot="primary-action"
      variant="primary"
      tone="critical"
      commandFor="delete-modal"
      command="--hide"
    >
      Delete product
    </s-button>
    <s-button
      slot="secondary-actions"
      variant="secondary"
      commandFor="delete-modal"
      command="--hide"
    >
      Cancel
    </s-button>
  </s-modal>
</s-stack>

html

<s-stack gap="base">
  <s-button tone="critical" commandFor="delete-modal" command="--show">
    Delete product
  </s-button>

  <s-modal id="delete-modal" heading="Delete product?">
    <s-stack gap="base">
      <s-text>Are you sure you want to delete "Winter jacket"?</s-text>
      <s-text tone="caution">This action cannot be undone.</s-text>
    </s-stack>

    <s-button
      slot="primary-action"
      variant="primary"
      tone="critical"
      commandFor="delete-modal"
      command="--hide"
    >
      Delete product
    </s-button>
    <s-button
      slot="secondary-actions"
      variant="secondary"
      commandFor="delete-modal"
      command="--hide"
    >
      Cancel
    </s-button>
  </s-modal>
</s-stack>

Modal with form fields

Description

Modal containing form fields demonstrating how to structure input fields within a modal. Click the button to open the modal.

jsx

<s-stack gap="base">
  <s-button variant="primary" commandFor="edit-modal" command="--show">
    Edit customer
  </s-button>

  <s-modal id="edit-modal" heading="Edit customer information" size="large">
    <s-stack gap="base">
      <s-text-field
        label="Customer name"
        name="name"
        value="Sarah Johnson"
       />

      <s-email-field
        label="Email address"
        name="email"
        value="sarah@example.com"
       />

      <s-text-field
        label="Phone number"
        name="phone"
        value="+1 555-0123"
       />

      <s-select label="Customer group" name="group">
        <s-option value="retail">Retail</s-option>
        <s-option value="wholesale" selected>
          Wholesale
        </s-option>
        <s-option value="vip">VIP</s-option>
      </s-select>
    </s-stack>

    <s-button
      slot="primary-action"
      variant="primary"
      commandFor="edit-modal"
      command="--hide"
    >
      Save changes
    </s-button>
    <s-button
      slot="secondary-actions"
      variant="secondary"
      commandFor="edit-modal"
      command="--hide"
    >
      Cancel
    </s-button>
  </s-modal>
</s-stack>

html

<s-stack gap="base">
  <s-button variant="primary" commandFor="edit-modal" command="--show">
    Edit customer
  </s-button>

  <s-modal id="edit-modal" heading="Edit customer information" size="large">
    <s-stack gap="base">
      <s-text-field
        label="Customer name"
        name="name"
        value="Sarah Johnson"
      ></s-text-field>

      <s-email-field
        label="Email address"
        name="email"
        value="sarah@example.com"
      ></s-email-field>

      <s-text-field
        label="Phone number"
        name="phone"
        value="+1 555-0123"
      ></s-text-field>

      <s-select label="Customer group" name="group">
        <s-option value="retail">Retail</s-option>
        <s-option value="wholesale" selected>Wholesale</s-option>
        <s-option value="vip">VIP</s-option>
      </s-select>
    </s-stack>

    <s-button
      slot="primary-action"
      variant="primary"
      commandFor="edit-modal"
      command="--hide"
    >
      Save changes
    </s-button>
    <s-button
      slot="secondary-actions"
      variant="secondary"
      commandFor="edit-modal"
      command="--hide"
    >
      Cancel
    </s-button>
  </s-modal>
</s-stack>

Different modal sizes

Description

Demonstrates various modal sizes for different content requirements. Click each button to see different modal sizes.

jsx

<s-stack gap="base">
  <s-stack direction="inline" gap="base">
    <s-button commandFor="small-modal" command="--show">
      Small modal
    </s-button>
    <s-button commandFor="large-modal" command="--show">
      Large modal
    </s-button>
  </s-stack>

  {/* Small modal for quick confirmations */}
  <s-modal id="small-modal" heading="Confirm action" size="small-100">
    <s-text>Are you sure you want to proceed?</s-text>
    <s-button
      slot="primary-action"
      variant="primary"
      commandFor="small-modal"
      command="--hide"
    >
      Confirm
    </s-button>
    <s-button
      slot="secondary-actions"
      variant="secondary"
      commandFor="small-modal"
      command="--hide"
    >
      Cancel
    </s-button>
  </s-modal>

  {/* Large modal for detailed content */}
  <s-modal id="large-modal" heading="Order details" size="large-100">
    <s-stack gap="base">
      <s-section>
        <s-heading>Order #1001</s-heading>
        <s-text>Placed on March 15, 2024</s-text>
      </s-section>

      <s-divider />

      <s-section>
        <s-heading>Items</s-heading>
        <s-stack gap="small">
          <s-text>Winter jacket - $89.99</s-text>
          <s-text>Wool scarf - $29.99</s-text>
          <s-text>Leather gloves - $45.99</s-text>
        </s-stack>
      </s-section>

      <s-divider />

      <s-text type="strong">Total: $165.97</s-text>
    </s-stack>

    <s-button
      slot="primary-action"
      variant="primary"
      commandFor="large-modal"
      command="--hide"
    >
      Close
    </s-button>
  </s-modal>
</s-stack>

html

<s-stack gap="base">
  <s-stack direction="inline" gap="base">
    <s-button commandFor="small-modal" command="--show">Small modal</s-button>
    <s-button commandFor="large-modal" command="--show">Large modal</s-button>
  </s-stack>

  <!-- Small modal for quick confirmations -->
  <s-modal id="small-modal" heading="Confirm action" size="small-100">
    <s-text>Are you sure you want to proceed?</s-text>
    <s-button
      slot="primary-action"
      variant="primary"
      commandFor="small-modal"
      command="--hide"
    >
      Confirm
    </s-button>
    <s-button
      slot="secondary-actions"
      variant="secondary"
      commandFor="small-modal"
      command="--hide"
    >
      Cancel
    </s-button>
  </s-modal>

  <!-- Large modal for detailed content -->
  <s-modal id="large-modal" heading="Order details" size="large-100">
    <s-stack gap="base">
      <s-section>
        <s-heading>Order #1001</s-heading>
        <s-text>Placed on March 15, 2024</s-text>
      </s-section>

      <s-divider></s-divider>

      <s-section>
        <s-heading>Items</s-heading>
        <s-stack gap="small">
          <s-text>Winter jacket - $89.99</s-text>
          <s-text>Wool scarf - $29.99</s-text>
          <s-text>Leather gloves - $45.99</s-text>
        </s-stack>
      </s-section>

      <s-divider></s-divider>

      <s-text type="strong">Total: $165.97</s-text>
    </s-stack>

    <s-button
      slot="primary-action"
      variant="primary"
      commandFor="large-modal"
      command="--hide"
    >
      Close
    </s-button>
  </s-modal>
</s-stack>

Modal without padding

Description

Modal with no padding for full-width content. Click to view the modal.

jsx

<s-stack gap="base">
  <s-button commandFor="image-modal" command="--show">
    View product image
  </s-button>

  <s-modal id="image-modal" heading="Product image" padding="none">
    <s-box background="subdued" padding="base">
      <s-text>Image would display here with full width</s-text>
    </s-box>

    <s-button
      slot="secondary-actions"
      variant="secondary"
      commandFor="image-modal"
      command="--hide"
    >
      Close
    </s-button>
  </s-modal>
</s-stack>

html

<s-stack gap="base">
  <s-button commandFor="image-modal" command="--show">
    View product image
  </s-button>

  <s-modal id="image-modal" heading="Product image" padding="none">
    <s-box background="subdued" padding="base">
      <s-text>Image would display here with full width</s-text>
    </s-box>

    <s-button
      slot="secondary-actions"
      variant="secondary"
      commandFor="image-modal"
      command="--hide"
    >
      Close
    </s-button>
  </s-modal>
</s-stack>

Was this page helpful?

Modal

Anchor to propertiesProperties

Anchor to eventsEvents

CallbackEventListener

CallbackEvent

Anchor to slotsSlots

Preview

Examples

Code

jsx

html

Anchor to usageUsage

Anchor to useful-forUseful for

Anchor to best-practicesBest practices

Anchor to content-guidelinesContent guidelines

Anchor to examplesExamples

Anchor to example-basic-usageBasic usage

Preview

Examples

Basic modal

Description

jsx

html

Modal with actions

Description

jsx

html

Modal with form fields

Description

jsx

html

Different modal sizes

Description

jsx

html

Modal without padding

Description

jsx

html