---
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/apis/modal
  md: https://shopify.dev/docs/api/app-home/apis/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"

  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"

  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\<typeof tagName> | null

* aftershow

  CallbackEventListener\<typeof tagName> | null

* hide

  CallbackEventListener\<typeof tagName> | null

* show

  CallbackEventListener\<typeof tagName> | 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 `ButtonGroup` or `Button` with a variant of `secondary` or `auto` are allowed.

### Examples

* #### Code

  ##### Default

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