---
title: Modal
description: >-
  Displays content in an overlay. Use to create a distraction-free experience
  such as a confirmation dialog or a settings panel.
api_name: app-home
source_url:
  html: 'https://shopify.dev/docs/api/app-home/polaris-web-components/overlays/modal'
  md: >-
    https://shopify.dev/docs/api/app-home/polaris-web-components/overlays/modal.md
---

# Modal

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

## Properties

* **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.

* **heading**

  **string**

  A title that describes the content of the Modal.

* **hideOverlay**

  **() => void**

  Method to hide an overlay.

* **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.

* **showOverlay**

  **() => void**

  Method to show an overlay.

* **size**

  **"small" | "small-100" | "base" | "large" | "large-100"**

  **Default: 'base'**

  Adjust the size of the Modal.

* **toggleOverlay**

  **() => void**

  Method to toggle the visiblity of an overlay.

## Events

Learn more about [registering events](https://shopify.dev/docs/api/app-home/using-polaris-components#event-handling).

* **afterhide**

  **CallbackEventListener\<TTagName> | null**

* **aftershow**

  **CallbackEventListener\<TTagName> | null**

* **hide**

  **CallbackEventListener\<TTagName> | null**

* **show**

  **CallbackEventListener\<TTagName> | null**

### CallbackEventListener

```ts
(EventListener & {
      (event: CallbackEvent<T>): void;
    }) | null
```

### CallbackEvent

```ts
Event & {
  currentTarget: HTMLElementTagNameMap[T];
}
```

## Slots

* **children**

  **HTMLElement**

  The content of the Modal.

* **primary-action**

  **HTMLElement**

  The primary action to perform.

  Only a `Button` with a variant of `primary` is allowed.

* **secondary-actions**

  **HTMLElement**

  The secondary actions to perform.

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

Examples

### Examples

* #### Code

  ##### jsx

  ```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

  ```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>
  ```

* #### Basic modal

  ##### Description

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

  ##### jsx

  ```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

  ```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

  ```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

  ```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

  ```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

  ```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

  ```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

  ```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

  ```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

  ```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>
  ```

## Usage

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`.

## Useful 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

## Best 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

## Content 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"