App Bridge & Polaris

Two different things

Where they come from

One wrapper in your admin layout switches everything on:

<AppProvider embedded apiKey={apiKey}>
  <s-app-nav>
    <s-link href="/app/products">Products</s-link>
  </s-app-nav>
  <Outlet />
</AppProvider>

Every page nested under app.jsx can now use s- tags and App Bridge, with nothing to import.

<script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>

Page structure

Three components give you the standard admin layout:

<s-page heading="Products">
  <s-section heading="All products">
    <s-stack gap="base">
      <s-text>Some content</s-text>
      <s-button variant="primary">Add product</s-button>
    </s-stack>
  </s-section>
</s-page>

• s-page — the page frame and title.
• s-section — a white card with an optional heading.
• s-stack — spacing between children. Use it instead of CSS margins.

s-stack takes direction="inline" for a row, plus gap, justifyContent and alignItems:

<s-stack direction="inline" gap="small" justifyContent="space-between">

<s-text tone="subdued">    // ignored — not a valid tone
<s-text color="subdued">   // correct

The components you will use most

Buttons follow the admin's own hierarchy — one primary action per section, everything else plain:

<s-button variant="primary">Save</s-button>
<s-button href="/app/products">Cancel</s-button>
<s-button tone="critical" variant="tertiary">Delete</s-button>

A button with href navigates; one with onClick runs code. Use href for links — it works with keyboard and middle-click, which a click handler does not.

Form fields are controlled

These components expect React-style controlled values: hold the value in state and update it on change.

const [title, setTitle] = useState("");

<s-text-field
  label="Title"
  value={title}
  onChange={(e) => setTitle(e.currentTarget.value)}
  error={errors.title}
  details="Shown on the product page"
/>

<s-select label="Status" value={status} onChange={(e) => setStatus(e.currentTarget.value)}>
  <s-option value="active">Active</s-option>
  <s-option value="draft">Draft</s-option>
</s-select>

<s-button onClick={() => fetcher.submit({ title }, { method: "post" })}>
  Save
</s-button>

Modals, without JavaScript

Modals are declarative. Give the modal an id, then point a button at it:

<s-button commandFor="gallery-modal" command="--show">
  Choose image
</s-button>

<s-modal id="gallery-modal" heading="Select an image" size="large">
  <s-stack gap="base">
    {/* modal content */}
  </s-stack>

  <s-button commandFor="gallery-modal" command="--hide">Close</s-button>
</s-modal>

No open/closed state, no useState, no refs. The button tells the modal what to do.

Toasts

The small confirmation that slides up from the bottom of the admin. It comes from App Bridge, not a component:

import { useAppBridge } from "@shopify/app-bridge-react";

const shopify = useAppBridge();

shopify.toast.show("Product saved");
shopify.toast.show("Could not save", { isError: true });

Show it after a save finishes:

useEffect(() => {
  if (fetcher.state === "idle" && fetcher.data) {
    shopify.toast.show(fetcher.data.message, { isError: !fetcher.data.success });
  }
}, [fetcher.state, fetcher.data, shopify]);

Toasts are for confirmations. Use s-banner for anything the user needs to read carefully or act on.

The resource picker

App Bridge opens Shopify's own product/collection/customer browser — search, filters and all — for free:

const selected = await shopify.resourcePicker({
  type: "product",
  multiple: false,
  filter: { variants: false, draft: false, archived: false },
});

if (!selected?.length) return;      // user cancelled
const product = selected[0];
product.id;       // "gid://shopify/Product/123"
product.title;

Always handle the cancel case — closing the picker resolves with nothing.

Navigation

Inside the embedded admin, use s-link or React Router's Link with app paths. App Bridge keeps the browser's address bar in sync, so the back button and bookmarks behave.

<s-link href="/app/products">Products</s-link>
<s-button href="/app/products/create" variant="primary">New</s-button>

To link out to the Shopify admin itself — a product's real admin page — use a full URL and open a new tab:

<s-button
  href={`https://admin.shopify.com/store/${shopHandle}/products/${numericId}`}
  target="_blank"
>View in admin</s-button>

Custom elements behave differently from React

These are real browser elements wrapped for React, and two habits do not carry over.

Also: style them with their own attributes, not CSS overrides. Internal structure is not a public API, and a CSS rule targeting their insides can break with any Shopify update. When you need layout that components do not offer, wrap them in your own <div> and style that.

A complete page

export default function Products() {
  const { products } = useLoaderData();
  const fetcher = useFetcher();
  const shopify = useAppBridge();
  const busy = fetcher.state !== "idle";

  useEffect(() => {
    if (fetcher.state === "idle" && fetcher.data?.message) {
      shopify.toast.show(fetcher.data.message, { isError: !fetcher.data.success });
    }
  }, [fetcher.state, fetcher.data, shopify]);

  return (
    <s-page heading="Products">
      <s-section>
        <s-stack direction="inline" gap="base" justifyContent="space-between">
          <s-text>{products.length} products</s-text>
          <s-button href="/app/products/create" variant="primary">
            Add product
          </s-button>
        </s-stack>
      </s-section>

      <s-section heading="All products">
        {products.length === 0 ? (
          <s-text color="subdued">No products yet.</s-text>
        ) : (
          <s-stack gap="small">
            {products.map((p) => (
              <s-stack key={p.id} direction="inline" justifyContent="space-between">
                <s-text>{p.title}</s-text>
                <s-button
                  tone="critical"
                  variant="tertiary"
                  disabled={busy}
                  onClick={() => fetcher.submit(
                    { intent: "delete", id: String(p.id) },
                    { method: "post" },
                  )}
                >Delete</s-button>
              </s-stack>
            ))}
          </s-stack>
        )}
      </s-section>
    </s-page>
  );
}

Common problems

Cheat sheet

# layout
<s-page heading> → <s-section heading> → <s-stack gap>

# stack
direction="inline"  gap="base"  justifyContent="space-between"

# buttons
variant="primary"            the one main action
tone="critical"              destructive
href=                        navigates (better than onClick for links)

# fields — controlled, submitted manually
value={x} onChange={(e) => setX(e.currentTarget.value)}
fetcher.submit({ x }, { method: "post" })

# modal — no state needed
<s-button commandFor="id" command="--show">
<s-modal id="id" heading size>           render it always

# App Bridge
shopify.toast.show(msg, { isError })
await shopify.resourcePicker({ type: "product" })   → then fetch the full record

# gotchas
blank page          Polaris script missing outside /app/*
empty form data     components don't submit natively
ignored spacing     invalid gap token
missing variants    picker truncates nested lists