Empty state

Every app has moments when there's nothing to show yet and some action is required of the merchant before they can manage resources. The empty state composition turns these blank screens into opportunities by guiding merchants toward their first action.

Include a clear explanation of what will appear here and a prominent call-to-action to help merchants get started. This composition follows proven design guidelines that help your app feel native to the Shopify admin. See Built for Shopify requirements for more details on these guidelines.

Anchor to ExamplesExamples

Anchor to Display an empty state with centered content and actionsDisplay an empty state with centered content and actions

Merchants need guidance and a clear next step when a list or page is empty. This pattern displays an empty state with centered content and primary and secondary actions. The grid centers content vertically and horizontally. Use the button group with slot="primary-action" and slot="secondary-actions" for clear next steps.

Preview

<s-section accessibilityLabel="Empty state section">

<s-grid gap="base" justifyItems="center" paddingBlock="large-400">

<s-box maxInlineSize="200px" maxBlockSize="200px">

{/* aspectRatio should match the actual image dimensions (width/height) */}

<s-image

aspectRatio="1/0.5"

src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"

alt="A stylized graphic of four characters, each holding a puzzle piece"

</s-box>

<s-grid justifyItems="center" maxInlineSize="450px" gap="base">

<s-stack alignItems="center">

<s-heading>Start creating puzzles</s-heading>

<s-paragraph>

Create and manage your collection of puzzles for players to enjoy.

</s-paragraph>

</s-stack>

<s-button-group>

<s-button

slot="secondary-actions"

aria-label="Learn more about creating puzzles"

{" "}

Learn more{" "}

</s-button>

<s-button slot="primary-action" aria-label="Add a new puzzle">

{" "}

Create puzzle{" "}

</s-button>

</s-button-group>

</s-grid>

</s-section>

<s-section accessibilityLabel="Empty state section">

<s-grid gap="base" justifyItems="center" paddingBlock="large-400">

<s-box maxInlineSize="200px" maxBlockSize="200px">

<s-image

aspectRatio="1/0.5"

src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"

alt="A stylized graphic of four characters, each holding a puzzle piece"

</s-box>

<s-grid

justifyItems="center"

maxInlineSize="450px"

gap="base"

<s-stack alignItems="center">

<s-heading>Start creating puzzles</s-heading>

<s-paragraph>

Create and manage your collection of puzzles for players to enjoy.

</s-paragraph>

</s-stack>

<s-button-group>

<s-button slot="secondary-actions" aria-label="Learn more about creating puzzles"> Learn more </s-button>

<s-button slot="primary-action" aria-label="Add a new puzzle"> Create puzzle </s-button>

</s-button-group>

</s-grid>

</s-section>

jsx

<s-section accessibilityLabel="Empty state section">
  <s-grid gap="base" justifyItems="center" paddingBlock="large-400">
    <s-box maxInlineSize="200px" maxBlockSize="200px">
      {/* aspectRatio should match the actual image dimensions (width/height) */}
      <s-image
        aspectRatio="1/0.5"
        src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"
        alt="A stylized graphic of four characters, each holding a puzzle piece"
      />
    </s-box>
    <s-grid justifyItems="center" maxInlineSize="450px" gap="base">
      <s-stack alignItems="center">
        <s-heading>Start creating puzzles</s-heading>
        <s-paragraph>
          Create and manage your collection of puzzles for players to enjoy.
        </s-paragraph>
      </s-stack>
      <s-button-group>
        <s-button
          slot="secondary-actions"
          aria-label="Learn more about creating puzzles"
        >
          {" "}
          Learn more{" "}
        </s-button>
        <s-button slot="primary-action" aria-label="Add a new puzzle">
          {" "}
          Create puzzle{" "}
        </s-button>
      </s-button-group>
    </s-grid>
  </s-grid>
</s-section>

html

<s-section accessibilityLabel="Empty state section">
  <s-grid gap="base" justifyItems="center" paddingBlock="large-400">
    <s-box maxInlineSize="200px" maxBlockSize="200px">
      <!-- aspectRatio should match the actual image dimensions (width/height) -->
      <s-image
        aspectRatio="1/0.5"
        src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"
        alt="A stylized graphic of four characters, each holding a puzzle piece"
      />
    </s-box>
    <s-grid
      justifyItems="center"
      maxInlineSize="450px"
      gap="base"
    >
    <s-stack alignItems="center">
      <s-heading>Start creating puzzles</s-heading>
      <s-paragraph>
        Create and manage your collection of puzzles for players to enjoy.
      </s-paragraph>
    </s-stack>
    <s-button-group>
      <s-button slot="secondary-actions" aria-label="Learn more about creating puzzles"> Learn more </s-button>
      <s-button slot="primary-action" aria-label="Add a new puzzle"> Create puzzle </s-button>
    </s-button-group>
    </s-grid>
  </s-grid>
</s-section>

Anchor to Navigate to create pageNavigate to create page

Use href attributes to navigate merchants to a create page when they click the primary action button.

<s-section>

<s-stack alignItems="center" padding="large-500">

<s-box maxInlineSize="200px">

<s-image

src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"

alt="No puzzles illustration"

aspectRatio="1/0.5"

</s-box>

<s-heading>Create your first puzzle</s-heading>

<s-paragraph>

Get started by creating a puzzle template. You can customize the number of pieces, shape, and difficulty level.

</s-paragraph>

<s-button href="/app/puzzles/new">Create puzzle</s-button>

</s-stack>

</s-section>

<s-section>

<s-stack alignItems="center" padding="large-500">

<s-box maxInlineSize="200px">

<s-image

src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"

alt="No puzzles illustration"

aspectRatio="1/0.5"

></s-image>

</s-box>

<s-heading>Create your first puzzle</s-heading>

<s-paragraph>

Get started by creating a puzzle template. You can customize the number of pieces, shape, and difficulty level.

</s-paragraph>

<s-button href="/app/puzzles/new">Create puzzle</s-button>

</s-stack>

</s-section>

jsx

<s-section>
  <s-stack alignItems="center" padding="large-500">
    <s-box maxInlineSize="200px">
      <s-image
        src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"
        alt="No puzzles illustration"
        aspectRatio="1/0.5"
      />
    </s-box>
    <s-heading>Create your first puzzle</s-heading>
    <s-paragraph>
      Get started by creating a puzzle template. You can customize the number of pieces, shape, and difficulty level.
    </s-paragraph>
    <s-button href="/app/puzzles/new">Create puzzle</s-button>
  </s-stack>
</s-section>

html

<s-section>
  <s-stack alignItems="center" padding="large-500">
    <s-box maxInlineSize="200px">
      <s-image
        src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"
        alt="No puzzles illustration"
        aspectRatio="1/0.5"
      ></s-image>
    </s-box>
    <s-heading>Create your first puzzle</s-heading>
    <s-paragraph>
      Get started by creating a puzzle template. You can customize the number of pieces, shape, and difficulty level.
    </s-paragraph>
    <s-button href="/app/puzzles/new">Create puzzle</s-button>
  </s-stack>
</s-section>

Anchor to Open Shopify interfaces with IntentsOpen Shopify interfaces with Intents

Use the Intents API to make empty state actions open native Shopify interfaces, allowing merchants to browse existing resources or create new ones without leaving your app.

{}

<s-section accessibilityLabel="Empty state with intents">

<s-grid gap="base" justifyItems="center" paddingBlock="large-400">

<s-box maxInlineSize="200px" maxBlockSize="200px">

<s-image

aspectRatio="1/0.5"

src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"

alt="Illustration showing product creation"

</s-box>

<s-grid justifyItems="center" maxInlineSize="450px" gap="base">

<s-stack alignItems="center">

<s-heading>No products yet</s-heading>

<s-paragraph>

Add products from your Shopify catalog to get started with quality auditing.

</s-paragraph>

</s-stack>

<s-button-group>

<s-button

slot="secondary-actions"

onClick={() => {

shopify.intents.invoke('browse:shopify/Product');

}}

Browse products

</s-button>

<s-button

slot="primary-action"

onClick={async () => {

const activity = await shopify.intents.invoke('create:shopify/Product');

const response = await activity.complete;

if (response.code === 'ok') {

shopify.toast.show('Product created');

}

}}

Create product

</s-button>

</s-button-group>

</s-grid>

</s-section>

<s-section accessibilityLabel="Empty state with intents">

<s-grid gap="base" justifyItems="center" paddingBlock="large-400">

<s-box maxInlineSize="200px" maxBlockSize="200px">

<s-image

aspectRatio="1/0.5"

src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"

alt="Illustration showing product creation"

></s-image>

</s-box>

<s-grid justifyItems="center" maxInlineSize="450px" gap="base">

<s-stack alignItems="center">

<s-heading>No products yet</s-heading>

<s-paragraph>

Add products from your Shopify catalog to get started with quality auditing.

</s-paragraph>

</s-stack>

<s-button-group>

<s-button slot="secondary-actions">Browse products</s-button>

<s-button slot="primary-action">Create product</s-button>

</s-button-group>

</s-grid>

</s-section>

<!--

JavaScript usage for the buttons:

// Browse products

shopify.intents.invoke('browse:shopify/Product');

// Create product

const activity = await shopify.intents.invoke('create:shopify/Product');

const response = await activity.complete;

if (response.code === 'ok') {

shopify.toast.show('Product created');

}

-->

jsx

{/* @validate-ignore: possibly 'undefined', Cannot invoke an object */}
<s-section accessibilityLabel="Empty state with intents">
  <s-grid gap="base" justifyItems="center" paddingBlock="large-400">
    <s-box maxInlineSize="200px" maxBlockSize="200px">
      <s-image
        aspectRatio="1/0.5"
        src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"
        alt="Illustration showing product creation"
      />
    </s-box>
    <s-grid justifyItems="center" maxInlineSize="450px" gap="base">
      <s-stack alignItems="center">
        <s-heading>No products yet</s-heading>
        <s-paragraph>
          Add products from your Shopify catalog to get started with quality auditing.
        </s-paragraph>
      </s-stack>
      <s-button-group>
        <s-button
          slot="secondary-actions"
          onClick={() => {
            shopify.intents.invoke('browse:shopify/Product');
          }}
        >
          Browse products
        </s-button>
        <s-button
          slot="primary-action"
          onClick={async () => {
            const activity = await shopify.intents.invoke('create:shopify/Product');
            const response = await activity.complete;
            if (response.code === 'ok') {
              shopify.toast.show('Product created');
            }
          }}
        >
          Create product
        </s-button>
      </s-button-group>
    </s-grid>
  </s-grid>
</s-section>

html

<!-- Empty state with Intents API actions -->
<!-- Note: Intents require JavaScript to invoke. This HTML shows the UI structure. -->
<s-section accessibilityLabel="Empty state with intents">
  <s-grid gap="base" justifyItems="center" paddingBlock="large-400">
    <s-box maxInlineSize="200px" maxBlockSize="200px">
      <s-image
        aspectRatio="1/0.5"
        src="https://cdn.shopify.com/static/images/polaris/patterns/callout.png"
        alt="Illustration showing product creation"
      ></s-image>
    </s-box>
    <s-grid justifyItems="center" maxInlineSize="450px" gap="base">
      <s-stack alignItems="center">
        <s-heading>No products yet</s-heading>
        <s-paragraph>
          Add products from your Shopify catalog to get started with quality auditing.
        </s-paragraph>
      </s-stack>
      <s-button-group>
        <s-button slot="secondary-actions">Browse products</s-button>
        <s-button slot="primary-action">Create product</s-button>
      </s-button-group>
    </s-grid>
  </s-grid>
</s-section>

<!-- 
JavaScript usage for the buttons:

// Browse products
shopify.intents.invoke('browse:shopify/Product');

// Create product
const activity = await shopify.intents.invoke('create:shopify/Product');
const response = await activity.complete;
if (response.code === 'ok') {
  shopify.toast.show('Product created');
}
-->

Was this page helpful?