App UI: Polaris and App Bridge

Three things cooperate inside an embedded page. The admin itself draws the surrounding chrome. Your app draws its own content in an iframe using Polaris web components. A small script, App Bridge, connects the two: it publishes the shopify global that the app calls, and it renders chrome elements (title bar, navigation, save bar) in the host page on the app’s behalf.

The drawing separates the three libraries that the rest of the page treats one by one.

Source: App Home reference

The default template (shopify app init with the React Router template, see Apps Overview and Scaffolding) never shows a script tag in its own source. The package @shopify/shopify-app-react-router renders them. Reading the package source of the version installed by the public template at commit 48b841a (2026-10-09, package 3.0.2; the registry now has 4.0.0) shows exactly what it does:

The template’s parent route shows the result. The route app/routes/app.tsx authenticates the request in its loader, passes the client ID to the browser and wraps all child routes:

Source: shopify-app-template-react-router (route app/routes/app.tsx)

The template’s tsconfig.json lists @shopify/polaris-types in types, so the s-* elements type-check in JSX. The template’s package.json pins @shopify/polaris-types to 1.0.1 on that commit, which is one reason the next section matters: a project created from it stays on Polaris 1 until someone changes it.

Under semantic versioning a script URL names either a channel that moves forward within one major version, or a pinned release that never changes. The versioning reference lists the options. To confirm the table against the live CDN, each URL was fetched on 2026-10-27 and the response body hashed (the first 12 hex digits of SHA-256 are shown; equal hashes mean identical files).

The observed facts match the documentation: polaris.js, polaris-1.js and polaris-1.1.js are the same file today, and so are polaris-2.js and polaris-2.0.js. The first pair will diverge when a 1.2 release ships, and the second when 2.1 does. The 2.x bundle is about 24 percent larger than 1.1, which fits the fact, explained in the next section, that it carries both appearances of the admin. The CDN responses allow cross-origin use (access-control-allow-origin: *) and are cached for 60 seconds with a five-minute stale-while-revalidate window (cache-control: max-age=60, stale-while-revalidate=300), so a channel update reaches merchants within minutes, not hours. That is the reason to pin a release when you need control over exactly when a change appears.

Source: Versioning for web components

The 2.0 release is about appearance, not about the component API.

To see how much of the component API moved, the published type packages were installed and compared on 2026-10-27. The tag list is identical between @shopify/polaris-types 1.1.0 and 2.0.0 (62 tag declarations in the type file, the same set), the only changed property in the machine-readable custom-elements manifest is a new loading property on s-thumbnail, and the type file lists 564 icon names in 1.1.0 and 605 in 2.0.0, with no icon removed (the new names are mostly -filled variants such as cart-down-filled and markets-euro-filled). Going from 1.0.1 to 1.1.0 added five tags (s-empty-state, s-number, s-press-button, s-progress, s-scroll-box) and ten icons. In other words, an app that already renders only Polaris web components does not have to change its markup to adopt 2.0; it has to load the new script, update the types and check the parts of its UI that Polaris does not control.

Source: Polaris 2.0 release candidate and @shopify/polaris-types on npm

The upgrade guide has three steps.

Step 1: load the new version. How depends on how the app loads Polaris today. An app with its own script tag changes the URL, as in the head snippet above. An app built from the React Router template sets polarisUrl in two places and keeps the two values identical:

Source: Update your app for Polaris 2

Both options need @shopify/shopify-app-react-router 2.1.0 or later and both are optional. If the values differ, the browser preloads one bundle (from the Link header) while the page runs another, which wastes bandwidth and can hide which version is really live. Do not add a Polaris script tag of your own next to AppProvider: that loads a second bundle and fails. Then install @shopify/polaris-types@^2.0.0 so the types describe the components that the app renders. To stay on exactly 2.0 when later 2.x releases ship, load polaris-2.0.js and install @shopify/polaris-types@~2.0.0.

Step 2: audit what Polaris does not control. Polaris elements restyle themselves; anything else keeps its old look. The guide asks for these checks:

Step 3: test both appearances. During the rollout a 2.0 app must be correct in the old and the new admin. The old one is any dev store without the redesign. The new one is a dev store created with the "Shopify admin’s new design" feature preview; with the CLI that is shopify store create dev with the --feature-preview new_admin_design flag. Nothing in the app changes between the two: the same bundle follows whichever admin surrounds it.

Source: Update your app for Polaris 2

For a production app the documented advice is the stable channel of the major you have tested (polaris-2.js), which gets bug fixes, accessibility work and new components without an edit. Pin an exact release (polaris-2.0.js) only when a release process needs to control the moment a visual change lands, and then schedule the bump, because pinned releases receive no normal fixes. Use the release-candidate URLs only on development and staging. A project created from the template today is on Polaris 1 until polarisUrl is set; given the 2027-05-01 Built for Shopify date, a new app that intends to qualify should set it on day one.

s-page is the outer wrapper of a page. In an embedded app it also coordinates its heading, breadcrumb and actions with the admin’s title bar, so the merchant sees one coherent header. It has a heading and an inlineSize property (small, base or large) and fills named slots:

The Polaris page has no slot for status next to the heading, so there is no equivalent of the old Polaris React titleMetadata; a status that matters goes into the page content, for example an s-badge inside a section.

Inside the page, s-section groups content with an optional heading, s-stack lays children out in a row or column (direction="inline" or "block", with a gap), s-grid builds columns, and s-box is the escape hatch with padding, border and background properties. Component properties use camelCase in JSX and in the DOM (accessibilityLabel, commandFor, gridTemplateColumns), while slot names are kebab-case (slot="primary-action"). Links and buttons use href, not the old React url.

Polaris components emit ordinary DOM events, so frameworks bind them the usual way (onClick, onInput, onChange in React and Preact; addEventListener or lowercase attributes in plain HTML).

Source: Using web components

The page below edits the roast date of two Pocket Coffee single-origin variants. It uses a page with a breadcrumb, a section with a status badge, a form with the automatic save bar, date fields, a primary button, App Bridge’s loading indicator and toast, and an authenticated fetch to the app’s own backend. The backend route and its token verification belong to Authentication and Access Scopes; here only the browser side is shown.

Source: Page, Save bar and Toast API

The status badge sits inside the section because the page has no slot for it. This file was type-checked, not rendered. On 2026-10-27 it passed tsc 5.9.3 in strict mode with jsx: react-jsx, @types/react 19.3.0, @shopify/polaris-types 2.0.0 and @shopify/app-bridge-types 0.7.3 (tsconfig types set to react, @shopify/polaris-types, @shopify/app-bridge-types). The same project rejected a deliberately wrong file:

The three errors show what the type package buys: an invented tone value, the non-existent s-card, and a misspelled property all fail at build time. Rendering the page needs a development store and shopify app dev, which require a Shopify login and were not run for this documentation.

A page without a framework is the same markup with a script tag (the component tags are real elements, so no build step is needed):

Source: Modal

The App Home reference recommends starting from patterns, pre-built combinations of components and APIs that also help an app meet Built for Shopify design requirements. Templates are whole-page layouts: homepage, resource index, details and settings. Compositions are smaller assemblies to place inside a template: account connection, app card, callout card, footer help, index table, interstitial navigation, media card, metrics card, resource list and setup guide. The Pocket Coffee app would use the settings template for its roast-date defaults, the index table composition for a list of variants, and the setup guide for onboarding.

Source: App Home page patterns

Polaris elements use shadow DOM, so app CSS cannot reach inside them, cannot target internal classes, and cannot replace their styles with .Polaris-* selectors from the old React library. App CSS can still style the native elements and wrappers that the app renders itself (a scrolling region, a sticky footer, an ellipsis) and can size or position a component host where ordinary layout rules apply. Use the documented component properties for the look of the component and keep custom CSS scoped to app-owned elements around it.

Some shopify.config values are set by the host (shop, the permanent myshopify.com domain; host; locale, the language of the admin user). Others are set with meta tags in the head:

Source: Config API

The documentation groups the APIs into three families.

Source: App Bridge APIs and web methods

Calls from the iframe to the app’s backend cannot rely on cookies (an embedded app has to work without third-party cookies). App Bridge replaces them with a signed ID token. Older documentation calls it a session token; the current name is ID token. When the app calls the global fetch() for a URL on its own origin or a subdomain, App Bridge’s fetch interceptor adds the token in the Authorization header and the admin user’s locale in Accept-Language, so usually the app never touches the token. Call shopify.idToken() only when a standard fetch is not involved, for example to authenticate a WebSocket handshake.

Source: ID Token API and Resource Fetching API

Send the token only to your own backend. Verifying its signature needs the app’s client secret, so a third-party service cannot check it without a credential that would let it mint tokens your app accepts. The server side of the exchange (verifying the token, trading it for an access token) is the subject of Authentication and Access Scopes.

An iframe app can query the Admin GraphQL API straight from the browser, without a backend route, using the URL scheme shopify:admin/api/graphql.json with the standard fetch(). App Bridge routes the request through the host frame and authenticates it. It must be enabled in shopify.app.toml:

Source: App configuration

direct_api_mode is online (requests use the online access token of the logged-in staff member) or offline (requests use the offline access token); embedded_app_direct_api_access is false when omitted. On 2026-10-27 Shopify CLI 5.0.0 accepted this file in shopify app build --no-input with the placeholder client ID 00000000000000000000000000000000 and rejected direct_api_mode = "sometimes" with "Invalid literal value". The requested scopes still decide what the queries may read.

The Pocket Coffee page can then read the roast date metafield of every Ethiopia variant in the browser:

Source: Resource Fetching API and App configuration

The query document was validated offline against the Admin GraphQL schema for 2026-10 (introspection result downloaded anonymously, 3,708 types) with graphql 16.14.2: it is valid, while a copy with metafeild instead of metafield is reported as Cannot query field "metafeild" on type "ProductVariant". Did you mean "metafield" or "metafields"?. It was not sent to a store. To pin the API version, put it in the URL (shopify:admin/api/2026-10/graphql.json); without it the default is used. Cost-based throttling, pagination and version rules are the subject of Admin GraphQL API. Use direct access for reads and small mutations that belong with the interface; keep long-running or secret-dependent work on the backend.

Source: Resource Picker API, Scopes API and Navigation API

These elements render in the admin, outside the iframe, and need only the App Bridge script.

Source: App nav, Title bar and Save bar

@shopify/app-bridge-react 4.2.14 (peer dependencies React and React DOM, any version) wraps the same features for React. Its entry point exports the components Modal, NavMenu, TitleBar and SaveBar, the hook useAppBridge, and re-exports the types of @shopify/app-bridge-types. The hook returns the shopify global, or a safe proxy during server-side rendering where the global does not exist, which makes it the right way to call App Bridge from a component that is also rendered on the server (as in React Router):

Source: useAppBridge

The current template does not need the React wrappers for navigation or the title bar; it uses s-app-nav and s-page directly, and only imports useAppBridge for toasts and intents. The npm package @shopify/app-bridge 3.7.12 belongs to the earlier generation (versions 3 and below, with createApp and action creators) and is not what current docs or the template use; the CDN script is the supported entry point.

Shopify publishes an incremental migration guide for iframe apps. Its sequence:

The guide gives a one-to-one or pattern replacement for about a hundred components; a representative selection:

Source: Migrate from Polaris React to Polaris web components

A few translation habits cover most call sites. Replace url with href. Use camelCase properties and kebab-case slot names. Read values from event.currentTarget.value (or checked). Connect buttons to overlays with commandFor and command. Replace imported React icons with the documented string name on s-icon or an icon property, checking the icon reference instead of guessing names. Do not rewrite a whole app in one change: migrate one slice, review the diff and test it in a development store before starting the next. Shopify’s AI Toolkit (and the Dev MCP server) can give a coding agent the current Polaris, App Bridge and pattern documentation for this work, but the guide’s advice stands: one route or self-contained feature at a time.

Unit-test environments such as jsdom do not load the CDN script, so s-* elements stay as un-upgraded custom-element hosts without a shadow DOM. This was confirmed on 2026-10-27 with jsdom 26.1.0: after parsing <s-button variant="primary">Save</s-button>, customElements.get('s-button') is undefined, shadowRoot is null, the variant attribute and the text are readable, and the element’s constructor is plain HTMLElement. Tests should therefore query the rendered custom-element tag and its attributes or properties, not roles or text that only exist in the shadow DOM; dispatch real DOM events instead of calling a React prop; mock window.shopify methods used by the slice; stub showOverlay, hideOverlay and toggleOverlay when a test controls an s-modal; and provide complete ResizeObserver and matchMedia mocks if the environment needs them. For UI extensions on API version 2026-04 and later Shopify ships @shopify/ui-extensions-tester (version 2026.10.0 on npm), which renders an extension in a standard DOM against typed mocks of the shopify global without a running host.

Source: Migrate from Polaris React and Automated testing for Shopify UI extensions

After the last slice and all dependent packages are migrated: delete imports of @shopify/polaris and @shopify/polaris-icons; remove AppProvider, Frame, PolarisTestProvider and the Polaris React stylesheet; remove packages that only supported it; delete .Polaris-* selectors and token overrides; remove the dependency and reinstall; and add a lint rule so it does not return. If a public, authentication or standalone route outside the admin still needs Polaris React, keep the dependency and scope the restriction to the embedded routes. An ESLint rule does that:

Source: ESLint no-restricted-imports and Migrate from Polaris React

Run with ESLint 9.39.5 on 2026-10-27 against a file importing Card and Page from @shopify/polaris and an icon from @shopify/polaris-icons, it reported two no-restricted-imports errors with the message above and exit code 1, and a file without those imports passed. For TypeScript projects the same rule goes in the @typescript-eslint configuration with the same options. Finish with a search of the tree for @shopify/polaris, @shopify/polaris-icons and .Polaris-.