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

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

## Examples

Component examples

### Basic usage