ux-empty-error-states

Empty, Loading & Error State UX for Shopify Polaris Apps

A practical, opinionated reference for the three states that make or break a Shopify embedded app: when there's nothing yet, when something is on its way, and when something went sideways. Pulled from Polaris docs, Remix pending UI docs, and real-world patterns.

---

1. EmptyState — when, how, and what to put inside

What it is

EmptyState is Polaris' purpose-built component for "this page/section is empty." It composes a centered illustration, a heading, optional body text, and a primary action (and optional secondary action). It is intended for whole-page-empty experiences, not tiny empty slots inside a card sidebar.

When to use it

Use EmptyState when:

• A list/table/chart has zero rows for first-time merchants (no products, no orders, no campaigns).
• A filtered/searched view returns zero matches (different copy, same component).
• A feature requires setup before it can be used (no connected account, no plan selected).
• A merchant landed on a page that needs onboarding context before they can act.

Do not use EmptyState for:

• Small empty slots inside a Card where a simple "No notes yet" sentence is enough.
• Form fields that aren't filled in — that's just normal state.
• Loading. Use SkeletonPage instead.
• Errors. Use a Banner (or a full-page error view) instead.

Anatomy

import { EmptyState, Page } from "@shopify/polaris";

<Page>
  <EmptyState
    heading="Manage your inventory transfers"
    action={{ content: "Add transfer", onAction: () => navigate("/transfers/new") }}
    secondaryAction={{
      content: "Learn more",
      url: "https://help.shopify.com/manual/inventory/transfers",
      external: true,
    }}
    image="https://cdn.shopify.com/s/files/.../empty-state.svg"
  >
    <p>Track and receive your incoming inventory from suppliers.</p>
  </EmptyState>
</Page>

Content rules

• Heading — a friendly sentence fragment, not a label. "Manage your inventory transfers," not "Transfers."
• Body — one or two sentences. Explain the value, not the mechanism.
• Primary action — verb-first, the single most important thing they can do. "Add transfer," "Import products," "Connect Stripe."
• Secondary action — almost always a "Learn more" link to Shopify docs or your own help article. Use external: true and the new-window icon will render.
• Image — a Polaris illustration or your own brand-consistent SVG. ~400×250px works well. Polaris recommends ~40px of white space above when nested inside a Card or Modal.