Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 55 ยท App Extensions

Polaris and App Home Design

Design your Shopify app's home inside the admin: Polaris web components, App Bridge navigation, the contextual save bar, toasts, and the layout rules merchants expect.

Your app's App Home is the page merchants see when they click your app in the Shopify admin. It is an ordinary web page that your server serves, but it is shown inside an iframe in the admin, next to Shopify's own screens. Merchants judge your app by how much that page feels like part of Shopify: the same spacing, the same buttons, the same way of saving changes. That consistent look is what Polaris provides.

This lesson covers the building blocks of a good App Home: Polaris web components for layout and controls, App Bridge for the things the iframe cannot do alone (navigation menu, save bar, toasts), and the design habits that make an app feel native. The earlier lessons on App Extensions and Admin UI Extensions showed UI that lives in a small slot; here the whole page is yours.

What runs here. Shopify's real components, scripts and admin cannot run on this site, so all real markup and code below is read-only. The two live examples are plain JavaScript stand-ins that model the behavior (dirty tracking, save bar, toasts, nav highlighting). They are not Polaris, and component names and attributes change between releases, so check the current Polaris documentation before copying anything.

Polaris web components

Polaris is Shopify's design system. Today it is delivered as web components: custom HTML elements whose names start with s-. You load one script, and elements such as <s-page>, <s-section>, <s-button> and <s-text-field> become available in any framework, or in plain HTML. Because they are web components, the same markup works in the React Router template, in a server-rendered page, and in extensions.

A typical page in the app template (read-only):

HTML
<s-page heading="Product tagger">
  <s-button slot="primary-action" variant="primary">Run now</s-button>

  <s-section heading="Rules">
    <s-stack direction="block" gap="base">
      <s-text-field label="Tag to add" name="tag" value="summer"></s-text-field>
      <s-banner tone="info">
        Rules run on products that match the collection you pick.
      </s-banner>
    </s-stack>
  </s-section>
</s-page>

Read it from the outside in:

  • <s-page> is the page frame. It gives you the heading, the breadcrumb area and named slots such as the primary action.
  • <s-section> is a card-like block with its own heading. Group related controls in one section.
  • <s-stack> arranges children with consistent spacing, so you do not write margin CSS.
  • <s-text-field>, <s-button> and <s-banner> are controls and feedback.

Two scripts make this work. The template adds them for you, so you rarely write these tags by hand, but it helps to know what they are:

HTML
<meta name="shopify-api-key" content="YOUR_APP_CLIENT_ID" />
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
<script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>

The shopify-api-key meta tag tells App Bridge which app it is serving. App Bridge also exposes a global shopify object (used below for toasts and the save bar) and takes care of the session token that Session Tokens for Embedded Apps explained.

Prefer the platform over custom CSS. Every pixel you restyle by hand is a pixel that will look wrong after the next Polaris update, in dark admin themes, or on a small screen. Use components and their properties (tone, variant, gap) rather than your own colors and margins.

Merchants expect your app's pages in the admin's left sidebar, under your app's name. You declare them with an <s-app-nav> element. It renders nothing on your page; App Bridge reads it and builds the sidebar entries.

HTML
<s-app-nav>
  <s-link href="/app">Home</s-link>
  <s-link href="/app/rules">Rules</s-link>
  <s-link href="/app/settings">Settings</s-link>
</s-app-nav>

Rules of thumb:

  • Keep it to a handful of top-level entries. Three to five is typical; more means your information architecture needs work.
  • Use root-relative paths inside your app. App Bridge keeps the admin URL in step with the iframe route, so back and forward buttons work.
  • Name items by what the merchant gets ("Rules"), not by your implementation ("Settings v2 table").
  • The first entry is your home. Merchants who click your app name land there.

The contextual save bar

Forms in the admin do not each invent their own "Save" button. Instead, when a merchant changes something, a contextual save bar slides in at the top with Save and Discard buttons, and it warns before they navigate away with unsaved edits. This is the single most recognisable "native" behavior, and Shopify asks apps to follow it.

The simplest way is to mark a form for the save bar:

HTML
<form data-save-bar onSubmit={handleSave} onReset={handleDiscard}>
  <s-text-field label="Tag to add" name="tag" value={tag}></s-text-field>
  <s-text-field label="Collection" name="collection" value={collection}></s-text-field>
</form>

With data-save-bar, App Bridge watches the form. When a field differs from its saved value the bar appears; Save submits the form, Discard resets it. For custom flows you can drive it from code with calls such as shopify.saveBar.show('my-bar') and shopify.saveBar.hide('my-bar').

The logic behind it is simple, and it is worth being able to write it yourself, because you will debug it. The first live example models it.

Node.js Save bar stand-in: dirty tracking

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that typing a value and then typing the original back makes the form clean again. Compare values with the saved copy rather than keeping a "something changed" flag, otherwise the bar stays up for no reason.

Toasts and feedback

A toast is a short message that confirms something happened and disappears. Use it for success of a quick action ("Rule saved"), not for errors the merchant must act on. App Bridge exposes it directly:

JavaScript
shopify.toast.show('Rule saved');

shopify.toast.show('Could not reach the server', {
  isError: true,
  duration: 8000,
});

Choose the right feedback for the situation:

Situation Use
Quick action succeeded Toast
Form field is invalid Inline error on that field (error property)
Something the merchant must fix, on the page <s-banner tone="critical">
Important but not urgent information <s-banner tone="info"> or warning
Irreversible action Confirmation dialog before, not a toast after

Never rely on a toast alone for errors: it vanishes, and a merchant who looked away never learns that their changes were lost.

Layout and design guidelines

Shopify publishes design guidelines for apps, and the app review checks them (see App Store Requirements and Review). The recurring ideas are:

  1. Start with the job. The home page should answer "what do I do next?" with one primary action, not a wall of settings.
  2. One primary action per page. Use the page's primary-action slot for it; other buttons are secondary.
  3. Show the empty state. A new merchant has no data. Explain the value in one sentence and offer a clear first step instead of an empty table.
  4. Use progressive disclosure. Put rarely used options in a collapsed section or a separate settings page.
  5. Handle loading, errors and long lists. Skeletons or spinners while loading, a banner with a retry for failures, and pagination (as in Pagination with Cursors) for lists.
  6. Be fast. The app's home loads inside an iframe on every visit. Slow first paint is one of the most common review complaints.
  7. Write like Shopify. Sentence case, plain verbs ("Save", not "Submit changes"), no marketing language in the admin.
  8. Be accessible. Components give you keyboard handling and labels for free; do not remove them. Always give inputs a label.
flowchart TD
    A["Merchant opens app"] --> B{"Has data?"}
    B -- "No" --> C["Empty state:<br/>one sentence + primary action"]
    B -- "Yes" --> D["Overview:<br/>status + list"]
    D --> E["Edit form"]
    E --> F{"Changes made?"}
    F -- "Yes" --> G["Save bar:<br/>Save / Discard"]
    G --> H["Toast on success"]
    F -- "No" --> D

A merchant's path through a well-behaved App Home: empty state, overview, edit, save bar, toast.

Highlighting the current page

Because App Bridge keeps the URL in step with your route, the sidebar can show which entry is active. Matching is by path: the entry whose path is the longest prefix of the current URL wins, so /app/rules/42 highlights "Rules" but /app alone highlights "Home". Writing that rule once makes it clear why the home entry (/app) must not match everything.

Node.js Which nav item is active?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The case /app/rulesets shows the reason for the href + '/' check: a plain startsWith('/app/rules') would wrongly highlight "Rules".

Common mistakes

  • Opening links with <a target="_top"> by accident. Inside the iframe, a plain link to another page of your app must stay in the frame. Use the router's link component or <s-link>; for the admin or external sites use App Bridge-aware links so the right window navigates.
  • Building your own save button and skipping the save bar. Merchants lose the unsaved-changes warning.
  • Using a toast for a failure that needs a decision.
  • Hand-written CSS that fights the components and breaks in dark mode.
  • Hiding the primary action in a menu or placing five equal buttons side by side.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main purpose of Polaris for an app's home page?

    Polaris is Shopify's design system. Using its components gives your pages the same layout, controls and accessibility as the admin around them.
  2. 2. Which element declares the entries that appear under your app in the admin sidebar?

    s-app-nav is read by App Bridge, which builds the sidebar navigation from the links inside it. The meta tag only identifies the app.
  3. 3. When should the contextual save bar be visible?

    The bar signals unsaved changes. It appears when something is dirty, hides again when the values match the saved copy, and warns before the merchant leaves with edits.
  4. 4. A background save failed and the merchant must retry. What is the best feedback?

    Toasts disappear, so a merchant who looked away would miss the failure. Persistent banners or inline errors keep the problem visible until it is handled.

Summary

  • App Home is your own page shown in an iframe in the admin; Polaris web components (s-page, s-section, s-stack, s-button, ...) make it look native.
  • App Bridge connects the iframe to the admin: s-app-nav for sidebar entries, data-save-bar or shopify.saveBar for the save bar, shopify.toast for toasts.
  • Compare current values with the saved copy to decide whether the form is dirty.
  • Use toasts for quick successes and banners or inline errors for anything that needs attention.
  • Follow the design habits: one primary action, empty states, progressive disclosure, fast loads, sentence-case copy.
  • Real components and App Bridge calls are read-only here; check the current Polaris docs for exact names.

Next, take your app beyond the admin: Customer Account and POS Extensions.