---
title: ui-modal
description: >-
  The Modal API allows you to display an overlay that prevents interaction with
  the rest of the app until dismissed.

   It is used by customizing your Modal content with the `ui-modal` element and then opening it with the `show()` instance method or the `shopify.modal.show('modal-id')` API.
api_name: app-bridge-library
source_url:
  html: 'https://shopify.dev/docs/api/app-bridge-library/web-components/ui-modal'
  md: 'https://shopify.dev/docs/api/app-bridge-library/web-components/ui-modal.md'
---

# ui-modal

The Modal API allows you to display an overlay that prevents interaction with the rest of the app until dismissed.

It is used by customizing your Modal content with the `ui-modal` element and then opening it with the `show()` instance method or the `shopify.modal.show('modal-id')` API.

## ui-modal element

The `ui-modal` element is available for use in your app. It configures a Modal to display in the Shopify Admin.

The content you provide can be simple HTML elements or a `src` URL that will be loaded. When adding custom content, you can only provide a single parent element (commonly a `div` or `form`).

* children

  HTMLCollection & UITitleBarAttributes

  The content to display within a Modal. You can provide a single HTML element with children and the [ui-title-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-title-bar) element to configure the Modal title bar.

* id

  string

  A unique identifier for the Modal

* src

  string

  The URL of the content to display within a Modal. If provided, the Modal will display the content from the provided URL and any children other than the [ui-title-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-title-bar) and [ui-save-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-save-bar) elements will be ignored.

* variant

  'small' | 'base' | 'large' | 'max'

  Default: "base"

  The size of the modal.

  Before the Modal is shown, this can be changed to any of the provided values. After the Modal is shown, this can can only be changed between `small`, `base`, and `large`.

### UITitleBarAttributes

* children

  The children of the title bar.

  ```ts
  any
  ```

* title

  The title of the title bar. Can also be set via \<code>document.title\</code>.

  ```ts
  string
  ```

```ts
export interface UITitleBarAttributes extends _UITitleBarAttributes {
  children?: any;
}
```

## ui-modal instance

The `ui-modal` element provides instance properties and methods to control the Modal.

* addEventListener

  (type: "show" | "hide", listener: EventListenerOrEventListenerObject) => void

  Add 'show' | 'hide' event listeners.

* content

  HTMLElement

  A getter/setter that is used to get the DOM content of the modal element and update the content after the modal has been opened.

* contentWindow

  Window | null

  A getter that is used to get the Window object of the modal iframe when the modal is used with a `src` attribute. This can only be accessed when the modal is open, so it is recommended to use `await modal.show()` before accessing this property.

* hide

  () => Promise\<void>

  Hides the save bar element

* removeEventListener

  (type: "show" | "hide", listener: EventListenerOrEventListenerObject) => void

  Remove 'show' | 'hide' event listeners.

* show

  () => Promise\<void>

  Shows the save bar element

* src

  string

  A getter/setter that is used to set modal src.

* toggle

  () => Promise\<void>

  Toggles the save bar element between the showing and hidden states

* variant

  Variant

  A getter/setter that is used to set modal variant.

### Variant

```ts
'small' | 'base' | 'large' | 'max'
```

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/app-bridge-library/modal.png)

## Examples

Modal options, variations, and events

### Modals with different options

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/app-bridge-library/modal-max.png)

### Modal events

### Updating the Modal once it is open

### Using a src URL to load content

## Related

[APIs - Modal](https://shopify.dev/docs/api/app-bridge-library/apis/modal)

[React Components - Modal Component](https://shopify.dev/docs/api/app-bridge-library/react-components/modal-component)

[Web Components - ui-title-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-title-bar)

[Web Components - ui-save-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-save-bar)