Empty state

Empty states are used when a list, table, or chart has no items or data to show. This is an opportunity to provide explanation or guidance to help merchants progress. The empty state component is intended for use when a full page in the admin is empty, and not for individual elements or areas in the interface.

Use to explain a single feature before merchants have used it.

import {Card, EmptyState} from '@shopify/polaris';
import React from 'react';

function EmptyStateExample() {
  return (
    <Card sectioned>
      <EmptyState
        heading="Manage your inventory transfers"
        action={{content: 'Add transfer'}}
        secondaryAction={{
          content: 'Learn more',
          url: 'https://help.shopify.com',
        }}
        image="https://cdn.shopify.com/s/files/1/0262/4071/2726/files/emptystate-files.png"
      >
        <p>Track and receive your incoming inventory from suppliers.</p>
      </EmptyState>
    </Card>
  );
}

Use to provide additional but non-critical context for a new product or feature. Can also be used to include a subdued call to action for secondary or tertiary actions.

import {Card, EmptyState, Link} from '@shopify/polaris';
import React from 'react';

function EmptyStateExample() {
  return (
    <Card sectioned>
      <EmptyState
        heading="Manage your inventory transfers"
        action={{content: 'Add transfer'}}
        secondaryAction={{
          content: 'Learn more',
          url: 'https://help.shopify.com',
        }}
        footerContent={
          <p>
            If you don’t want to add a transfer, you can import your inventory
            from{' '}
            <Link monochrome url="/settings">
              settings
            </Link>
            .
          </p>
        }
        image="https://cdn.shopify.com/s/files/1/0262/4071/2726/files/emptystate-files.png"
      >
        <p>Track and receive your incoming inventory from suppliers.</p>
      </EmptyState>
    </Card>
  );
}
import {Card, EmptyState} from '@shopify/polaris';
import React from 'react';

function EmptyStateExample() {
  return (
    <Card sectioned>
      <EmptyState
        heading="Upload a file to get started"
        action={{content: 'Upload files'}}
        image="https://cdn.shopify.com/s/files/1/0262/4071/2726/files/emptystate-files.png"
        fullWidth
      >
        <p>
          You can use the Files section to upload images, videos, and other
          documents. This example shows the content with a centered layout and
          full width.
        </p>
      </EmptyState>
    </Card>
  );
}

Props

Want to help make this feature better? Please share your feedback.

interface EmptyStateProps
heading?string

The empty state heading.

imagestring

The path to the image to display. The image should have ~40px of white space above when empty state is used within a card, modal, or navigation component.

largeImage?string

The path to the image to display on large screens.

imageContained?boolean

Whether or not to limit the image to the size of its container on large screens.

fullWidth?boolean

Whether or not the content should span the full width of its container.

children?React.ReactNode

Elements to display inside empty state.

action?

Primary action for empty state.

secondaryAction?

Secondary action for empty state.

footerContent?React.ReactNode

Secondary elements to display below empty state actions.

Best practices

Empty states should:

  • Orient merchants by clearly explaining the benefit and utility of a product or feature
  • Simplify a complicated experience by focusing on a few key features and benefits
  • Use simple and clear language that empowers merchants to move their business forward
  • Be encouraging and never make merchants feel unsuccessful or guilty because they haven’t used a product or feature
  • Explain the steps merchants need to take to activate a product or feature
  • Use illustrations thoughtfully as outlined in our illustration guidelines
  • Use only one primary call-to-action button
  • Provide extra spacing at the bottom of an empty state that is within content (card, modal, or navigation) to match the image that was passed into the component with a white space above it of 40px

Content guidelines

Title

Empty state titles should:

  • Be action-oriented: encourage merchants to take the step required to activate the product or feature

Do

  • Create orders and send invoices

Don’t

  • Orders and invoices

Subtitle

Empty state subtitles act like body content. They should:

  • Describe or explain what’s in the empty state title or item title
  • Be conversational: include articles such as the, a, and an

Primary action

Buttons are used for the most important actions you want merchants to take. They should be:

  • Clear and predictable: merchants should be able to anticipate what will happen when they click a button. Never deceive merchants by using misleading titles.

Do

  • Create order
  • Buy shipping label

Don’t

  • New order
  • Buy
  • Action-led: buttons should always lead with a strong verb that encourages action. To provide enough context to merchants use the {verb}+{noun} format on buttons except in the case of common actions like Save, Close, Cancel, or OK.

Do

  • Activate Apple Pay
  • View shipping settings

Don’t

  • Try Apple Pay
  • View your settings
  • Scannable: avoid unnecessary words and articles such as the, an, or a.

Do

  • Add menu item

Don’t

  • Add a menu item

Secondary action

Secondary actions are used for less important actions such as “Learn more” or “Close” buttons. They should follow all the other content rules outlined for primary buttons.



Accessibility

Empty state illustrations are implemented as decorative images, so they use an empty alt attribute and are skipped by technologies like screen readers.