Skip to content
CommerceGeek home

Debugging Polaris Web Component Issues in Embedded Shopify Apps

When Polaris web components or the Admin frame change, embedded app UI can behave differently. Here is how to isolate link, modal and navigation problems and report them clearly.

Magnifying glass over a modal and link inside a framed app page nested within an admin frame.
Published
16 Nov 2026
As of
26 Oct 2026

If you maintain an embedded Shopify app and its links, modals or navigation started acting oddly after an Admin or Polaris update, this guide is for you. It covers how the pieces fit together, a repeatable way to narrow down the cause, and what a useful bug report contains.

Know what is actually running

Before you chase a bug, get clear on what is actually running. An iframe-based App Home app renders its UI inside an iframe using web components, and it talks to the rest of Shopify admin through App Bridge, a JavaScript SDK. So you have your page inside the frame, the Polaris components it uses, and the admin around it. A link, a modal or a navigation change can come from any of those layers.

Polaris web components are built on the Web Components standard, so they behave like native HTML elements. The App Home docs say you can use them in any framework or with vanilla JavaScript. That helps when debugging. Open the browser's element inspector and you are looking at real elements, not a framework-specific abstraction. It also means your framework's own routing or event handling may be sitting between you and the component, which is worth ruling out early.

The Polaris web component library for App Home is versioned, and the App Home reference documents version 2.0 as the latest stable version. Tip: before you start, write down the library version your app loads, plus the basics of your setup. Note how you run it locally (the App Home docs describe Shopify CLI's dev command, which starts a dev server and creates a tunnel), which framework you use, and whether you enabled direct API access in your configuration file. Then, if behaviour changes after an update, you can tell which layer moved: the ones you control, like your code and pinned version, or the ones Shopify controls, like the admin frame around your app. That separation makes a bug report far easier to act on.

Separate your code from the platform

Start by taking your own code out of the picture. The App Home docs say Polaris components are built on the Web Components standard, so they work like native HTML elements. You can use them in any framework or with vanilla JavaScript, just like a button or an input. That means you can test one in plain JavaScript, without React, a router or anything else you've wired around it.

So build a minimal page with one component. No router, no state library, no shared providers. Render the link, modal or button that misbehaves and see what it does. If the problem vanishes, the cause is likely in your framework wiring. Look at how your router intercepts clicks, how your state decides when a modal is open, or how your framework re-renders the element. If the problem stays, it is more likely the component itself or the Admin frame around your iframe. That is also the version you can attach to a bug report, because someone else can run it without your app.

One more thing to keep in mind. The Shopify Changelog says the Admin has been restyled, with a new frame, colours, type, spacing and icons, and navigation is now collapsible. We can't tell you that this causes any particular bug. But it is reasonable to suspect the surrounding frame when an overlay sits oddly or your app's available space changes, because your iframe now lives in a different amount of room. Check your minimal page with the navigation open and collapsed. If the difference follows the frame, you have a useful lead.

Investigating links, modals and navigation

Start with links, and ask one question: who handled the click? It could be your router, the browser's default behaviour or the host Admin. The App Home docs describe an iframe app that renders with web components and talks to the rest of Shopify admin through App Bridge. That setup gives you three possible handlers, and this checklist is reasoning from it, not documented behaviour. Add a temporary click listener in the capture phase and log the event target and whether default was prevented. Then check whether the page changed inside the iframe or the top window navigated. In dev tools, the frame selector in the console shows which context you are in. If you see the wrong frame, look at how the link is declared before you blame the component.

For modals, inspect the DOM before you touch any CSS. Find where the overlay actually renders: inside your iframe, or somewhere your styles can't reach. This tends to help because most stacking and focus bugs come from assuming the wrong container. Then check stacking order and focus. Open the modal, press Tab and watch where focus lands. Close it and confirm focus returns to the control that opened it. Test with the Admin navigation both expanded and collapsed. The Shopify Changelog says the admin has been restyled with a new frame, and that navigation is now collapsible. That changes the space your iframe gets, so a layout that looked fine before may now sit differently. The changelog doesn't describe modal or link behaviour, so treat any change you see as something to verify, not something already explained.

For navigation, look for double handling. One click can fire your router and also trigger a default browser or host action, which shows up as two history entries or a flicker. Log each click and watch the network panel to see what fires. One request per click is what you'd expect. Then confirm the URL changes in the frame you expect. If you're running through Shopify CLI's dev server tunnel, remember Shopify reaches your local app through that tunnel, so check the tunnel is up before you chase a UI bug. When you report an issue, include the component version you used, the steps, which frame navigated, and the click log. That gives the maintainers something they can reproduce.

Use your dev tooling to get a clean test loop

Start with a loop you can trust. Run shopify app dev from Shopify CLI. It starts a dev server and creates a tunnel, so Shopify can reach the app running on your machine. That means you can edit code locally and see the embedded result in the Admin without deploying anything.

Do it on a development store, and change one thing at a time. Bump the Polaris web component version, or tweak one link or modal, then reload and check. This tends to help because when a link, overlay or navigation behaviour shifts, you know which change caused it. It also keeps Admin restyling separate from your own changes. The changelog notes the Admin has a new frame, colours, type, spacing and icons, and collapsible navigation. Some visual differences may come from that rather than from your code.

Next, rule out the API before you blame the UI. The Developer Dashboard now shows API request volume, error rates, webhook health and a filterable log of requests made to Shopify. If a panel looks empty or a modal never fills with data, check that log first. A clean log points you back to the front end. If your front-end code calls the Admin GraphQL API directly, also check that embedded_app_direct_api_access is enabled in your configuration file, as the App Home docs describe. Without it, those calls won't work, and the symptom can look like a broken component.

Reporting an issue so it gets fixed

A good report lets someone reproduce the problem in minutes. Start with the Polaris web component version, because the App Home library is versioned and the reference documents version 2.0 as the latest stable. Then name the exact component and the attributes you set on it. Add a minimal reproduction: a small app or page with only that component, run through the dev server that Shopify CLI starts with its tunnel, so nobody has to untangle your wider codebase.

Write the steps as a numbered list, then give expected behaviour and actual behaviour on separate lines. Note your browser. Also say whether it happens with the Admin navigation collapsed. The Shopify changelog says the admin has been restyled and navigation is now collapsible, so frame and spacing changes could plausibly affect overlays and links. We can't say that is the cause, but it is a cheap thing to test and it narrows the search. A short screen recording helps too, especially for modal stacking or a link that opens in the wrong place.

Say what changed and when: a Polaris version bump, an Admin update you noticed, or neither. Keep each report to one issue, so a link problem and a modal problem get separate threads. For the merchant side, tell support which workflow breaks, such as editing a product or approving an order action, and who can no longer finish it. Stick to what you observed and don't guess at wider effects. If your app uses the Developer Dashboard, you can also mention any error rates or request log entries that line up with the failure.

Get the weekly digest

One email every Monday: the week’s new guides and articles, plus the Shopify deadlines coming up and what’s been announced. Free, and you can unsubscribe in one click.

Sources

  1. App Home · shopify.dev · accessed 22 Oct 2026
  2. Shopify Changelog · changelog.shopify.com · accessed 22 Oct 2026

AI-assisted, reviewed by Scott. Every claim is checked against the sources above.