Skip to contentShopify logoPolaris

App settings layout

Lets merchants scan and find groups of settings in apps.

Discuss on GitHub

How it helps merchants

App settings page with two columns
  1. In the left column, glanceable labels and descriptions are listed to make it easier for merchants to scan the page and quickly find what they are looking for.
  2. In the right column, settings are grouped in cards to make it easier for merchants to configure a setting after it's been found, or to configure multiple settings that might belong together.

Use when merchants need to:

Find and change app settings
This pattern is used specifically for finding and updating individual app settings within the Shopify admin.

Using this pattern

This pattern uses the AlphaStack, AlphaCard, Columns and Box components.

Edit in Sandbox
// This example is for guidance purposes. Copying it will come with caveats.
function AppSettingsLayoutExample() {
  const { smUp } = useBreakpoints();
  return (
    <Page
      divider
      primaryAction={{ content: "View on your store", disabled: true }}
      secondaryActions={[
        {
          content: "Duplicate",
          accessibilityLabel: "Secondary action label",
          onAction: () => alert("Duplicate action"),
        },
      ]}
    >
      <AlphaStack gap={{ xs: "8", sm: "4" }}>
        <Columns columns={{ xs: "1fr", md: "2fr 5fr" }} gap="4">
          <Box
            as="section"
            paddingInlineStart={{ xs: 4, sm: 0 }}
            paddingInlineEnd={{ xs: 4, sm: 0 }}
          >
            <AlphaStack gap="4">
              <Text as="h3" variant="headingMd">
                InterJambs
              </Text>
              <Text as="p" variant="bodyMd">
                Interjambs are the rounded protruding bits of your puzzlie piece
              </Text>
            </AlphaStack>
          </Box>
          <AlphaCard roundedAbove="sm">
            <AlphaStack gap="4">
              <TextField label="Interjamb style" />
              <TextField label="Interjamb ratio" />
            </AlphaStack>
          </AlphaCard>
        </Columns>
        {smUp ? <Divider borderStyle="base" /> : null}
        <Columns columns={{ xs: "1fr", md: "2fr 5fr" }} gap="4">
          <Box
            as="section"
            paddingInlineStart={{ xs: 4, sm: 0 }}
            paddingInlineEnd={{ xs: 4, sm: 0 }}
          >
            <AlphaStack gap="4">
              <Text as="h3" variant="headingMd">
                Dimensions
              </Text>
              <Text as="p" variant="bodyMd">
                Interjambs are the rounded protruding bits of your puzzlie piece
              </Text>
            </AlphaStack>
          </Box>
          <AlphaCard roundedAbove="sm">
            <AlphaStack gap="4">
              <TextField label="Horizontal" />
              <TextField label="Interjamb ratio" />
            </AlphaStack>
          </AlphaCard>
        </Columns>
      </AlphaStack>
    </Page>
  )
}

Useful to know

  • Don't include a description unless it's helpful. Section header with no description on an app settings page
  • Place grouped settings within cards. App settings page with section headings and grouped settings
  • Stack all setting groups vertically on the page. App settings page with two vertically stacked sections

Related resources

  • See another two-column layout in use in the Resource detail layout pattern.
  • See a single-column layout in use in the Resource index layout pattern.
  • Learn more about Layout in the app design guidelines.
  • Check out the Polaris Spacing guidelines to understand Polaris grid and spacing scale.