Page

Use to build the outer wrapper of a page, including the page title and associated actions.

Use for detail pages, which should have pagination and breadcrumbs, and also often have several actions.

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

function PageExample() {
  return (
    <Page
      breadcrumbs={[{content: 'Products', url: '/products'}]}
      title="3/4 inch Leather pet collar"
      titleMetadata={<Badge status="success">Paid</Badge>}
      subtitle="Perfect for any pet"
      compactTitle
      primaryAction={{content: 'Save', disabled: true}}
      secondaryActions={[
        {
          content: 'Duplicate',
          accessibilityLabel: 'Secondary action label',
          onAction: () => alert('Duplicate action'),
        },
        {
          content: 'View on your store',
          onAction: () => alert('View on your store action'),
        },
      ]}
      actionGroups={[
        {
          title: 'Promote',
          accessibilityLabel: 'Action group label',
          actions: [
            {
              content: 'Share on Facebook',
              accessibilityLabel: 'Individual action label',
              onAction: () => alert('Share on Facebook action'),
            },
          ],
        },
      ]}
      pagination={{
        hasPrevious: true,
        hasNext: true,
      }}
    >
      <Card title="Credit card" sectioned>
        <p>Credit card information</p>
      </Card>
    </Page>
  );
}

Use to create a custom primary action.

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

function PageExample() {
  return (
    <Page
      breadcrumbs={[{content: 'Settings', url: '/settings'}]}
      title="General"
      primaryAction={
        <Button
          primary
          connectedDisclosure={{
            accessibilityLabel: 'Other save actions',
            actions: [{content: 'Save as new'}],
          }}
        >
          Save
        </Button>
      }
    >
      <Card title="Credit card" sectioned>
        <p>Credit card information</p>
      </Card>
    </Page>
  );
}

Use when a primary action functions better as part of the page content instead of in the page header.

import {Page, Card, Stack, Button} from '@shopify/polaris';
import React from 'react';

function PageExample() {
  return (
    <Page
      breadcrumbs={[{content: 'Orders', url: '/orders'}]}
      title="#1085"
      secondaryActions={[
        {content: 'Print'},
        {content: 'Unarchive'},
        {content: 'Cancel order'},
      ]}
      pagination={{
        hasPrevious: true,
        hasNext: true,
      }}
    >
      <Card sectioned title="Fulfill order">
        <Stack alignment="center">
          <Stack.Item fill>
            <p>Buy postage and ship remaining 2 items</p>
          </Stack.Item>
          <Button primary>Continue</Button>
        </Stack>
      </Card>
    </Page>
  );
}

Used to visually indicate that the secondary page action is destructive.

import {Page} from '@shopify/polaris';
import React from 'react';

function PageExample() {
  return (
    <Page
      title="General"
      secondaryActions={[{content: 'Delete', destructive: true}]}
    >
      <p>Page content</p>
    </Page>
  );
}

Use to create a custom secondary action.

import {Page, Button} from '@shopify/polaris';
import React from 'react';

function PageExample() {
  return (
    <Page
      title="General"
      secondaryActions={
        <Button
          connectedDisclosure={{
            accessibilityLabel: 'Other save actions',
            actions: [{content: 'Save as new'}],
          }}
        >
          Save
        </Button>
      }
    >
      <p>Page content</p>
    </Page>
  );
}

Use when merchants or their staff will benefit from context on why a page action is disabled.

import {Page, Button} from '@shopify/polaris';
import React from 'react';

function PageExample() {
  return (
    <Page
      title="Product"
      primaryAction={{
        content: 'Save',
      }}
      secondaryActions={[
        {
          content: 'Import',
          disabled: true,
          helpText: 'You need permission to import products.',
        },
      ]}
    />
  );
}

Use when the page title benefits from secondary content.

import {Page, Card} from '@shopify/polaris';
import {ArrowDownMinor} from '@shopify/polaris-icons';
import React from 'react';

function PageExample() {
  return (
    <Page
      breadcrumbs={[{content: 'Products', url: '/products'}]}
      title="Invoice"
      subtitle="Statement period: May 3, 2019 to June 2, 2019"
      secondaryActions={[{content: 'Download', icon: ArrowDownMinor}]}
    >
      <Card title="Credit card" sectioned>
        <p>Credit card information</p>
      </Card>
    </Page>
  );
}

Use when a secondary action links to another website. Actions marked external open in a new browser tab.

import {Page, Card} from '@shopify/polaris';
import {ExternalMinor} from '@shopify/polaris-icons';
import React from 'react';

function PageExample() {
  return (
    <Page
      title="Jar With Lock-Lid"
      primaryAction={{content: 'Save', disabled: true}}
      secondaryActions={[
        {
          content: 'Promote',
          external: true,
          icon: ExternalMinor,
          url: 'https://www.facebook.com/business/learn/facebook-page-build-audience',
        },
      ]}
    >
      <Card title="Credit card" sectioned>
        <p>Credit card information</p>
      </Card>
    </Page>
  );
}

Use when the page doesn’t represent a list of objects or a detail view for an object.

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

function PageExample() {
  return (
    <Page
      breadcrumbs={[{content: 'Settings', url: '/settings'}]}
      title="General"
      primaryAction={{content: 'Save'}}
    >
      <Card title="Credit card" sectioned>
        <p>Credit card information</p>
      </Card>
    </Page>
  );
}

Use for layouts that benefit from more screen width, such as wide tables or lists.

import {Page, Card} from '@shopify/polaris';
import {PlusMinor} from '@shopify/polaris-icons';
import React from 'react';

function PageExample() {
  return (
    <Page
      fullWidth
      title="Orders"
      primaryAction={{content: 'Create order', icon: PlusMinor}}
      secondaryActions={[{content: 'Export'}]}
      pagination={{
        hasNext: true,
      }}
    >
      <Card title="Credit card" sectioned>
        <p>Credit card information</p>
      </Card>
    </Page>
  );
}

Use a narrow width layout if the page supports a single unified task. When merchants must review the entire page contents to complete their goal, this layout helps focus their attention in a single path from top to bottom.

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

function PageExample() {
  return (
    <Page
      narrowWidth
      breadcrumbs={[{content: 'Orders', url: '/orders'}]}
      title="Add payment method"
      primaryAction={{content: 'Save', disabled: true}}
    >
      <Card title="Credit card" sectioned>
        <p>Credit card information</p>
      </Card>
      <PageActions
        primaryAction={{content: 'Save', disabled: true}}
        secondaryActions={[{content: 'Delete'}]}
      />
    </Page>
  );
}

Use action groups for sets of actions that relate to one another, particularly when there are too many to display as secondary actions. Note that these groups will be further rolled up into a single action for smaller displays so that actions do not wrap or overflow the page bounds.

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

function PageExample() {
  return (
    <Page
      title="Products"
      actionGroups={[
        {
          title: 'Copy',
          onClick: (openActions) => {
            alert('Copy action');
            openActions();
          },
          actions: [{content: 'Copy to clipboard'}],
        },
        {
          title: 'Promote',
          disabled: true,
          actions: [{content: 'Share on Facebook'}],
        },
        {
          title: 'More actions',
          actions: [
            {content: 'Duplicate'},
            {content: 'Print'},
            {content: 'Unarchive'},
            {content: 'Cancel order'},
          ],
        },
      ]}
    >
      <Card title="Credit card" sectioned>
        <p>Credit card information</p>
      </Card>
    </Page>
  );
}

Title metadata appears immediately after the page’s title. Use it to communicate brief, important and non-interactive status information about an entire page.

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

function PageExample() {
  return (
    <Page
      breadcrumbs={[{content: 'Products', url: '/products'}]}
      title="Jar With Lock-Lid"
      titleMetadata={<Badge status="attention">Verified</Badge>}
      primaryAction={{content: 'Save', disabled: true}}
      secondaryActions={[
        {content: 'Duplicate'},
        {content: 'View on your store'},
      ]}
      pagination={{
        hasPrevious: true,
        hasNext: true,
      }}
    >
      <Card title="Credit card" sectioned>
        <p>Credit card information</p>
      </Card>
    </Page>
  );
}

Use when the page needs visual separation between the page header and the content.

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

function PageExample() {
  return (
    <Page
      breadcrumbs={[{content: 'Settings', url: '/settings'}]}
      title="General"
      divider
    >
      <Card title="Credit card" sectioned>
        <p>Credit card information</p>
      </Card>
    </Page>
  );
}

Props

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

interface PageProps
children?React.ReactNode

The contents of the page.

fullWidth?boolean

Remove the normal max-width on the page.

narrowWidth?boolean

Decreases the maximum layout width. Intended for single-column layouts.

divider?boolean

Displays a divider between the page header and the page content.

titleHidden?boolean

Visually hide the title.

primaryAction?any

Primary page-level action.

pagination?

Page-level pagination.

breadcrumbs?( | )[]

Collection of breadcrumbs.

secondaryActions?any

Collection of secondary page-level actions.

actionGroups?[]

Collection of page-level groups of secondary actions.

additionalNavigation?React.ReactNode

Warning
Additional navigation markup.

additionalMetadata?any
onActionRollup?(hasRolledUp: boolean) => void

Callback that returns true when secondary actions are rolled up into action groups, and false when not.

title?string

Page title, in large type.

subtitle?string

Page subtitle, in regular type.

titleMetadata?React.ReactNode

Important and non-interactive status information shown immediately after the title.

compactTitle?boolean

Removes spacing between title and subtitle.

Best practices

The page component should:

  • Always provide a title for the page header.
  • Always provide breadcrumbs when a page has a parent page.
  • Be organized around a primary activity. If that primary activity is a single action, provide it as a primary button in the page header.
  • Provide other page-level actions as secondary actions in the page header.
  • When the page represents an object of a certain type, provide pagination links to the previous and next object of the same type.

Content guidelines

Title

Titles should:

  • Describe the page in as few words as possible.
  • Be the name of the object type (pluralized) when the page is a list of objects. For a list of orders, the page title should be “Orders”.
  • Not be truncated.

App icon

App icons should:

  • Provide their app icon
  • Only be provided for pages that are part of a Shopify app

The content of each breadcrumb link should be the title of the page to which it links.

Page header actions

Page header action labels should be:

  • Clear and predictable: merchants should be able to anticipate what will happen when they click a page action. Never deceive merchants by mislabeling an action.

  • Action-led: they should always lead with a strong verb that encourages action. To provide enough context to merchants, use the {verb}+{noun} format.

Do

  • Create order
  • View in Postmates

Don’t

  • Create
  • Postmates deliveries
  • Short: for secondary actions, when the noun represents the same object as the page itself, a verb alone may be used. If there is ambiguity (such as with the verb “Cancel”), always use the {verb}+{noun} format.

    In the context of the orders list page:

Do

  • Import
  • Export

Don’t

  • Import orders
  • Export orders
  • Scannable: avoid unnecessary words and articles such as the, an, or a.

Do

Add menu item

Don’t

Add a menu item