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

```html
<ui-modal id="my-modal">
  <p>Message</p>
  <ui-title-bar title="Title">
    <button variant="primary">Label</button>
    <button onclick="document.getElementById('my-modal').hide()">Label</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```

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

### _UIModalAttributes

### children

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

value: `string`

A unique identifier for the Modal

### src

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

value: `'small' | 'base' | 'large' | 'max'`

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

value: `any`

The children of the title bar.

### title

value: `string`

The title of the title bar. Can also be set via `document.title`.

## Related

- [Modal](https://shopify.dev/docs/api/app-bridge-library/apis/modal)
- [Modal Component](https://shopify.dev/docs/api/app-bridge-library/react-components/modal-component)
- [ui-title-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-title-bar)
- [ui-save-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-save-bar)

## Examples

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.


### Modals with different options

```html
<ui-modal id="my-modal" variant="max">
  <div></div>
  <ui-title-bar>
    <button variant="primary">Primary action</button>
    <button>Secondary action</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```

```html
<ui-modal id="my-modal" variant="large">
  <p>Hello, World!</p>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```

```html
<ui-modal id="my-modal" variant="max">
  <form data-save-bar>
    <label>
      Name:
      <input name="submitted-name" autocomplete="name" />
    </label>
    <button>Save</button>
  </form>
  <ui-title-bar>
    <button variant="primary">Save</button>
    <button>Cancel</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```

```html
<ui-modal id="my-modal">
  <p>Hello, World!</p>
  <ui-title-bar title="My Modal"></ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```

```html
<ui-modal id="my-modal">
  <p>Hello, World!</p>
  <ui-title-bar>
    <button variant="primary" onclick="console.log('Saving')">Save</button>
    <button onclick="console.log('Cancelling')">Cancel</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```

```html
<ui-modal id="my-modal">
  <p>If you delete this resource, it can't be undone.</p>
  <ui-title-bar title="Delete this resource">
    <button variant="primary" tone="critical" onclick="console.log('Deleting')">
      Delete
    </button>
    <button onclick="console.log('Cancelling')">Cancel</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```


### Modal events

```html
<ui-modal id="my-modal">
  <p>Message</p>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

<script>
  document.getElementById('my-modal').addEventListener('show', () => {
    console.log('Modal is showing');
  });
</script>

```

```html
<ui-modal id="my-modal">
  <div>
    <button onclick="document.getElementById('my-modal').hide()">
      Hide Modal
    </button>
  </div>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Show Modal</button>

<script>
  document.getElementById('my-modal').addEventListener('hide', () => {
    console.log('Modal is hiding');
  });
</script>

```


### Updating the Modal once it is open

```html
<ui-modal id="my-modal">
  <div>
    <p>Message</p>
    <button id="add-content">Add element</button>
  </div>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

<script>
  const button = document.getElementById('add-content');
  button.addEventListener('click', () => {
    const p = document.createElement('p');
    p.textContent = 'Lorem ipsum';

    const modal = document.getElementById('my-modal');
    modal.content.appendChild(p);
  });
</script>

```

```html
<ui-modal id="my-modal">
  <div>
    <p>Message</p>
    <button id="add-content">Add element</button>
  </div>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

<script>
  const button = document.getElementById('add-content');
  button.addEventListener('click', () => {
    const p = document.createElement('p');
    p.textContent = 'Lorem ipsum';

    const modal = document.getElementById('my-modal');
    modal.content.appendChild(p);
  });
</script>

```


### Using a src URL to load content

```html
// main app
<ui-modal id="my-modal" src="/my-route">
  <ui-title-bar title="Title">
    <button variant="primary">Label</button>
    <button onclick="document.getElementById('my-modal').hide()">Label</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

// my-route.html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
    <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
  </head>

  <body>
    <h1>My separate route</h1>
  </body>
</html>

```

```html
// main app
<script>
  window.addEventListener('message', (ev) => {
    console.log('Message received in main app:', ev.data);
  });

  window.addEventListener('load', async () => {
    const modal = document.getElementById('src-modal');
    await modal.show();
    modal.contentWindow.postMessage('Hello from the main app', location.origin);
  });
</script>

<ui-modal id="my-modal" src="/my-route">
  <ui-title-bar title="Title">
    <button variant="primary">Label</button>
    <button onclick="document.getElementById('my-modal').hide()">Label</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

// my-route.html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
    <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
  </head>

  <body>
    <button
      onclick="window.opener.postMessage('Hello from the modal', location.origin)"
    >
      Send message
    </button>
    <script>
      window.addEventListener('message', (ev) => {
        console.log('Message received in modal:', ev.data);
      });
    </script>
  </body>
</html>

```

```html
// main app
<ui-modal src="/my-route" variant="max" id="my-modal"></ui-modal>
<button onclick="shopify.modal.show('my-modal')">Open</button>
<ui-modal id="my-nested-modal">
  <p>Message</p>
</ui-modal>

// my-route.html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
    <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
  </head>
  <body>
    <button onclick="window.opener.shopify.modal.show('my-nested-modal')">Open</button>
  </body>
</html>
```

## ui-modal instance

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

### _UIModalElement

### addEventListener

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

Add 'show' | 'hide' event listeners.

### content

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

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

value: `() => Promise<void>`

Hides the save bar element

### removeEventListener

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

Remove 'show' | 'hide' event listeners.

### show

value: `() => Promise<void>`

Shows the save bar element

### src

value: `string`

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

### toggle

value: `() => Promise<void>`

Toggles the save bar element between the showing and hidden states

### variant

value: `Variant`

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

## Related

- [Modal](https://shopify.dev/docs/api/app-bridge-library/apis/modal)
- [Modal Component](https://shopify.dev/docs/api/app-bridge-library/react-components/modal-component)
- [ui-title-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-title-bar)
- [ui-save-bar](https://shopify.dev/docs/api/app-bridge-library/web-components/ui-save-bar)

## Examples

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.


### Modals with different options

```html
<ui-modal id="my-modal" variant="max">
  <div></div>
  <ui-title-bar>
    <button variant="primary">Primary action</button>
    <button>Secondary action</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```

```html
<ui-modal id="my-modal" variant="large">
  <p>Hello, World!</p>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```

```html
<ui-modal id="my-modal" variant="max">
  <form data-save-bar>
    <label>
      Name:
      <input name="submitted-name" autocomplete="name" />
    </label>
    <button>Save</button>
  </form>
  <ui-title-bar>
    <button variant="primary">Save</button>
    <button>Cancel</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```

```html
<ui-modal id="my-modal">
  <p>Hello, World!</p>
  <ui-title-bar title="My Modal"></ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```

```html
<ui-modal id="my-modal">
  <p>Hello, World!</p>
  <ui-title-bar>
    <button variant="primary" onclick="console.log('Saving')">Save</button>
    <button onclick="console.log('Cancelling')">Cancel</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```

```html
<ui-modal id="my-modal">
  <p>If you delete this resource, it can't be undone.</p>
  <ui-title-bar title="Delete this resource">
    <button variant="primary" tone="critical" onclick="console.log('Deleting')">
      Delete
    </button>
    <button onclick="console.log('Cancelling')">Cancel</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

```


### Modal events

```html
<ui-modal id="my-modal">
  <p>Message</p>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

<script>
  document.getElementById('my-modal').addEventListener('show', () => {
    console.log('Modal is showing');
  });
</script>

```

```html
<ui-modal id="my-modal">
  <div>
    <button onclick="document.getElementById('my-modal').hide()">
      Hide Modal
    </button>
  </div>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Show Modal</button>

<script>
  document.getElementById('my-modal').addEventListener('hide', () => {
    console.log('Modal is hiding');
  });
</script>

```


### Updating the Modal once it is open

```html
<ui-modal id="my-modal">
  <div>
    <p>Message</p>
    <button id="add-content">Add element</button>
  </div>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

<script>
  const button = document.getElementById('add-content');
  button.addEventListener('click', () => {
    const p = document.createElement('p');
    p.textContent = 'Lorem ipsum';

    const modal = document.getElementById('my-modal');
    modal.content.appendChild(p);
  });
</script>

```

```html
<ui-modal id="my-modal">
  <div>
    <p>Message</p>
    <button id="add-content">Add element</button>
  </div>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

<script>
  const button = document.getElementById('add-content');
  button.addEventListener('click', () => {
    const p = document.createElement('p');
    p.textContent = 'Lorem ipsum';

    const modal = document.getElementById('my-modal');
    modal.content.appendChild(p);
  });
</script>

```


### Using a src URL to load content

```html
// main app
<ui-modal id="my-modal" src="/my-route">
  <ui-title-bar title="Title">
    <button variant="primary">Label</button>
    <button onclick="document.getElementById('my-modal').hide()">Label</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

// my-route.html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
    <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
  </head>

  <body>
    <h1>My separate route</h1>
  </body>
</html>

```

```html
// main app
<script>
  window.addEventListener('message', (ev) => {
    console.log('Message received in main app:', ev.data);
  });

  window.addEventListener('load', async () => {
    const modal = document.getElementById('src-modal');
    await modal.show();
    modal.contentWindow.postMessage('Hello from the main app', location.origin);
  });
</script>

<ui-modal id="my-modal" src="/my-route">
  <ui-title-bar title="Title">
    <button variant="primary">Label</button>
    <button onclick="document.getElementById('my-modal').hide()">Label</button>
  </ui-title-bar>
</ui-modal>

<button onclick="document.getElementById('my-modal').show()">Open Modal</button>

// my-route.html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
    <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
  </head>

  <body>
    <button
      onclick="window.opener.postMessage('Hello from the modal', location.origin)"
    >
      Send message
    </button>
    <script>
      window.addEventListener('message', (ev) => {
        console.log('Message received in modal:', ev.data);
      });
    </script>
  </body>
</html>

```

```html
// main app
<ui-modal src="/my-route" variant="max" id="my-modal"></ui-modal>
<button onclick="shopify.modal.show('my-modal')">Open</button>
<ui-modal id="my-nested-modal">
  <p>Message</p>
</ui-modal>

// my-route.html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
    <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
  </head>
  <body>
    <button onclick="window.opener.shopify.modal.show('my-nested-modal')">Open</button>
  </body>
</html>
```