App window

The app window component displays a fullscreen modal window for complex workflows that need dedicated screen space. The content is specified by the src property and should point to a route within your app. The app window covers the entire screen, with a top bar controlled by the Shopify admin that allows users to exit.

For most dialogs, we recommend using the Polaris modal component, which automatically determines whether the modal should display inside your app or as a fullscreen overlay and removes the need for separate App Bridge API control.

Anchor to PropertiesProperties

Attributes for the app window element. This element displays a fullscreen modal window in the Shopify admin.

Anchor to src src string required: The URL of the content to display within the app window. Must point to a route within your app that renders the window content. The URL is loaded in an iframe when the window opens. Commonly used for multi-step workflows, bulk editors, or detailed views that need full-screen space.
Anchor to id id string: A unique identifier you assign to the app window element. Used when connecting buttons via commandFor or accessing the element with document.getElementById(). Choose a descriptive name like "settings-window" or "edit-modal".

Anchor to Instance methodsInstance methods

Instance properties and methods available on the app window element for programmatic control.

Anchor to addEventListener addEventListener (type: "show" | "hide", listener: EventListenerOrEventListenerObject) => void: Adds an event listener for app window lifecycle events. Supported events: show fires when the window opens, hide fires when the window closes. Commonly used for tracking analytics, updating UI state, or cleaning up resources when the window closes.
Anchor to contentWindow contentWindow Window | null: Returns the Window object of the app window iframe, or null if the window is closed. Use this to communicate with the iframe content via postMessage() or access its document. Only accessible when the app window is open.
Anchor to hide hide () => Promise<void>: Closes the app window. Returns a Promise that resolves when the window is fully hidden. Any unsaved changes in forms with data-save-bar will prompt the user before closing. Commonly used for programmatic close after completing a workflow.
Anchor to removeEventListener removeEventListener (type: "show" | "hide", listener: EventListenerOrEventListenerObject) => void: Removes a previously added event listener. Pass the same event type and listener function that was used with addEventListener(). Commonly used for cleanup when a component unmounts to prevent memory leaks.
Anchor to show show () => Promise<void>: Opens the app window and displays the content from the src URL. Returns a Promise that resolves when the window is fully visible. Use await or .then() to run code after the window opens. Commonly used for launching workflows triggered by user actions.
Anchor to src src string: Gets or sets the URL of the content displayed in the app window. Changing this value while the window is open navigates to the new URL. Commonly used for dynamic navigation within an open window.
Anchor to toggle toggle () => Promise<void>: Toggles the app window between open and closed states. Returns a Promise that resolves when the transition completes. Opens the window if closed, closes it if open. Commonly used for toggle buttons that control window visibility.

Anchor to ExamplesExamples

Anchor to Show and hideShow and hide

Open a fullscreen modal for complex workflows. This example uses the command attribute on a button to toggle the app window.

Show and hide

Open a fullscreen modal for complex workflows. This example uses the [`command`](/docs/api/app-home/polaris-web-components/actions/button#properties-propertydetail-command) attribute on a button to toggle the app window.

html

<s-app-window id="app-window" src="/app-window-content.html"></s-app-window>

<s-button command="--show" commandFor="app-window">Open App Window</s-button>

<s-button command="--hide" commandFor="app-window">Close App Window</s-button>

Anchor to Title bar headingTitle bar heading

Add context to fullscreen workflows. This example sets a title using the page component with the heading attribute.

Title bar heading

html

<s-app-window src="/app-window-content.html"></s-app-window>

// app-window-content.html

<s-page heading="Product editor"></s-page>

Anchor to Title bar actionsTitle bar actions

Provide actions in fullscreen workflows. This example adds primary and secondary action buttons to the title bar using page slots.

Title bar actions

html

<s-app-window src="/app-window-content.html"></s-app-window>

// app-window-content.html

<s-page heading="Product editor">

<s-button slot="primary-action" onClick="shopify.toast.show('Save')">Save</s-button>

<s-button slot="secondary-actions" onClick="shopify.toast.show('Preview')">Preview</s-button>

</s-page>

Anchor to Title bar accessory badgeTitle bar accessory badge

Show status in fullscreen workflows. This example displays a status badge using the accessory slot with tone for color.

Title bar accessory badge

html

<s-app-window src="/app-window-content.html"></s-app-window>

// app-window-content.html

<s-page heading="Edit Product">

<s-badge slot="accessory" tone="warning">Draft</s-badge>

<s-button slot="primary-action">Save</s-button>

</s-page>

Anchor to Title bar icons and menusTitle bar icons and menus

Add icons and dropdown menus to actions. This example pairs icon buttons with commandFor to create dropdown menus.

Title bar icons and menus

Add icons and dropdown menus to actions. This example pairs icon buttons with [`commandFor`](/docs/api/app-home/polaris-web-components/actions/button#properties-propertydetail-commandFor) to create dropdown menus.

html

<s-app-window src="/app-window-content.html"></s-app-window>

// app-window-content.html

<s-page heading="Product Details">

<s-button slot="primary-action" icon="save">Save</s-button>

<s-button slot="secondary-actions" commandFor="actions-menu" icon="menu">More actions</s-button>

<s-menu id="actions-menu">

<s-button icon="duplicate">Duplicate</s-button>

<s-button icon="archive">Archive</s-button>

<s-button icon="delete" tone="critical">Delete</s-button>

</s-menu>

</s-page>

Anchor to Instance methodsInstance methods

Control the app window programmatically. This example calls the show(), hide(), and toggle() methods.

Instance methods

html

<s-app-window id="app-window" src="/app-window-content.html"></s-app-window>

<s-button onClick="document.getElementById('app-window').show()">Show App Window</s-button>

<s-button onClick="document.getElementById('app-window').hide()">Hide App Window</s-button>

Anchor to Command attributeCommand attribute

Control the app window declaratively. This example uses the command and commandFor attributes on buttons.

Command attribute

Control the app window declaratively. This example uses the [`command`](/docs/api/app-home/polaris-web-components/actions/button#properties-propertydetail-command) and [`commandFor`](/docs/api/app-home/polaris-web-components/actions/button#properties-propertydetail-commandFor) attributes on buttons.

html

<s-app-window id="app-window" src="/app-window-content.html"></s-app-window>

<s-button command="--show" commandFor="app-window">Open App Window</s-button>

<s-button command="--hide" commandFor="app-window">Hide App Window</s-button>

<s-button command="--toggle" commandFor="app-window">Toggle App Window</s-button>

Anchor to Form with save barForm with save bar

Prevent data loss in fullscreen forms. This example integrates the save bar using data-save-bar to track unsaved changes.

Form with save bar

html

<s-app-window src="/app-window-content.html"></s-app-window>

// app-window-content.html

<s-page heading="Product editor">

<s-text-field label="Product title" name="productTitle"></s-text-field>

<s-text-area label="Description" name="description"></s-checkbox>

</form>

</s-page>

Anchor to Best practicesBest practices

Open only via explicit user action: Launch app windows from buttons that clearly indicate a fullscreen experience will open. Never open automatically on page load.
Set descriptive titles: Use the page component inside your app window content to set a heading that clearly describes the current task.
Handle unsaved changes: Add data-save-bar to forms to automatically prompt merchants before they exit with unsaved changes. See Save Bar API.
Return to context on close: Ensure closing the app window returns merchants to where they started. Don't navigate them elsewhere unexpectedly.

Was this page helpful?