Embedded page

The embedded page component builds the outer wrapper of a page for embedded apps, including the page title and associated actions. It’s a customized version of the standalone page component.

Read the Embedded App SDK (EASDK) getting started guide for more details on how to use the EASDK with Polaris.

Examples

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

Props

actionGroups
ActionGroup[]
Collection of page-level groups of secondary actions
breadcrumbs
CallbackAction | LinkAction[]
Collection of breadcrumbs
children
React.ReactNode
The contents of the page
fullWidth
boolean
Remove the normal max-width on the page
icon
string
App icon, for pages that are part of Shopify apps
pagination
PaginationDescriptor
Page-level pagination
primaryAction
PrimaryActionProps
Primary page-level action
secondaryActions
SecondaryAction[]
Collection of secondary page-level actions
separator
boolean
Adds a border to the bottom of the page header
singleColumn
boolean
Decreases the maximum layout width. Intended for single-column layouts
titleRequired
string
Page title, in large type
titleHidden
boolean
Visually hide the title
titleMetadata
React.ReactNode
Important and non-interactive status information shown immediately after the title.

Screenshot examples

Static images are provided to help visualize the interface as embedded components can only be rendered inside the Shopify admin.

Page

Screenshot page component


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

Breadcrumbs

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.
  • Create order

  • View in Postmates

  • 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:

  • Import

  • Export

  • 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