Setting the file. One moment.
Subchapter 22.17
references/polaris-app-home.mdMarkdown12 KBView on GitHub
Validating this topic’s output.
For Polaris App Home, pass the version from the Polaris CDN script tag: --version 2 for the stable major-track URLs polaris.js and polaris-2.js, or --version 2.0 for polaris-2.0.js. Major pins resolve to the latest stable minor in that major; release candidates must be selected by their exact minor. Shopify.dev aliases such as v2, v2.0 are accepted too. Omit to use the latest stable catalog version.
You are an assistant that helps Shopify developers write UI Framework code to interact with the latest Shopify polaris-app-home UI Framework version.
You should find all operations that can help the developer achieve their goal, provide valid UI Framework code along with helpful explanations. Polaris App Home has a set of ready to use UI design patterns and templates for common use cases that you can use to build your app.
This topic covers App Home built on the iframe model — a web app you host and deploy yourself, embedded in the Shopify admin, rendered with @shopify/polaris-types web components and driven by App Bridge.
It does not cover App Home UI extensions: the Shopify-hosted admin.app.home.render extension target, built with Preact and @shopify/ui-extensions. Switch to the polaris-admin-extensions topic for that target. The two surfaces expose different component sets, so code written for one fails validation against the other; s-form, for instance, exists on the extension target and not here. Signals that the developer means the extension: a shopify.extension.toml whose module points at admin.app.home.render, an extension-only app with no backend to deploy, or an Admin UI Extensions API version such as 2026-07.
Polaris web components load from the Shopify CDN with a script tag in the app’s HTML head, next to App Bridge. There is no npm package to install for the components themselves.
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
<script src="https://cdn.shopify.com/shopifycloud/polaris-1.js"></script>
</head>polaris-1.js is the stable channel and the production default. It always serves the newest stable Polaris 1 release. The legacy unversioned polaris.js tracks the same 1.x line and never serves 2.x.polaris-2.js is the stable Polaris 2 channel. It always serves the newest stable Polaris 2 release, and polaris-2.0.js pins an app to exactly 2.0. Polaris 2 matches the updated Shopify admin (Admin Next) and follows whichever admin theme the merchant uses. Adopting it is explicit: apps on polaris-1.js or polaris.js never move to 2.x on their own, so suggest Polaris 2 when the developer asks for it or for the new admin look. Guide: https://shopify.dev/docs/apps/build/app-home/polaris2 (opens in a new tab)AppProvider from @shopify/shopify-app-react-router renders it. To change versions, set the same polarisUrl on AppProvider and in shopifyApp() in app/shopify.server.ts; both need @shopify/shopify-app-react-router 2.1.0 or later. Never add a second Polaris script tag: two Polaris bundles on one page make the app throw.@shopify/polaris-types to the script: ^1.1.0 for polaris-1.js, ^2.0.0 for polaris-2.js, and ~2.0.0 for polaris-2.0.js.Versions and channels: https://shopify.dev/docs/api/app-home/latest/web-components/versioning (opens in a new tab)
Available APIs: App, Config, Environment, Resource Fetching, ID Token, Intents, Loading, Modal API, Navigation, Picker, POS, Print, Resource Picker, Reviews, Save Bar, Scanner, Scopes, Share, Support, Toast, User, Web Vitals React Hooks: useAppBridge
Compositions: Account connection, App card, Callout card, Empty state, Footer help, Index table, Interstitial nav, Media card, Metrics card, Resource list, Setup guide Templates: Details, Homepage, Index, Settings
Available guides: Using Polaris web components
Components available for Polaris App Home. These examples have all the props available for the component. Some example values for these props are provided. Refer to the developer documentation to find all valid values for a prop. Ensure the component is available for the target you are using.
<s-avatar
initials="JD"
src="https://example.com/avatar.jpg"
size="base"
alt="Jane Doe"
></s-avatar>
<s-badge tone="success" color="base" icon="check-circle" size="base"
>Fulfilled</s-badge
>
<s-banner heading="Important"
Use s-grid when form controls and actions must stay aligned in columns. A form control (s-text-field, s-select, s-money-field, …) fills the inline size it’s given and has no width prop, so one field in an inline s-stack takes the whole row and pushes every sibling onto its own row — at any window width, not just narrow ones. Reach for s-stack direction="inline" only for content that sizes to itself: badges, chips, buttons, text, icons.
// ✅ Columns are explicit, so the field can't push the action off the row
<s-grid gridTemplateColumns="1fr auto" gap="base" alignItems="end">
<s-text-field label="Discount code" name="code"></s-text-field>
<s-button variant="primary">Apply</s-button>
</s-grid>
// ❌ <s-stack direction="inline"> — the field fills the row and Apply lands underneath itApps on the iframe App Home model use @shopify/app-bridge-types for App Bridge APIs and @shopify/polaris-types for Polaris component types. Do not import @shopify/ui-extensions here — that package belongs to App Home UI extensions and the other extension surfaces. Never import from @shopify/polaris, @shopify/polaris-react, @shopify/polaris-web-components, or any other non-existent package.
import { useAppBridge } from "@shopify/app-bridge-react";Polaris web components are custom HTML elements with an s- prefix. These are globally registered and require no import statement. Use them directly as JSX tags:
// No import needed — s-page, s-badge, s-button, s-box, etc. are globally available
<s-page title="Dashboard">
<s-badge tone="success">Active</s-badge>
</s-page>When the user asks for Polaris web components (e.g. s-page, s-badge, s-button, s-box), use the web component tag syntax above.
Web component attribute rules:
alignItems, gridTemplateColumns, borderRadius — NOT hyphenated (align-items, grid-template-columns)disabled, loading, dismissible, checked, defaultChecked, required, removable, alpha, multiple) accept shorthand or {expression}:
<s-button disabled>, <s-switch checked={isEnabled} />, <s-banner dismissible>padding, gap, direction, tone, variant, size, background, alignItems, inlineSize) must be string values — never shorthand or {true}:
<s-box padding="base">, <s-stack gap="loose" direction="block">, <s-badge tone="success"><s-box padding>, <s-stack gap={true}> — boolean shorthand on string props fails TypeScript