Layout
Layout design is the process of arranging visual elements such as text, images, and shapes on a page.
Apps have a variety of available layouts. These layouts adapt the app body content to every screen size and device type. Selecting the proper layout for the task at hand will benefit your app's merchant experience.
![The responsive layout grid.](/assets/apps/design-guidelines/layout/responsive-layout-grid.png)
Responsive layout grid
Anchor link to section titled "Responsive layout grid"The Polaris Layout component provides built-in responsiveness. The following breakpoints are applied in the Shopify admin. Take these into into consideration when you build your app.
Breakpoint | Minimum viewport size | Maximum viewport size |
---|---|---|
xs | 0 | 489px |
sm | 490px | 767px |
md | 768px | 1039px |
lg | 1040px | 1399px |
xl | 1440px | ∞ |
![A responsive app on a desktop and mobile device.](/assets/apps/design-guidelines/layout/responsive-layout-grid-mobile.png)
Must Do
Design your app to be responsive and adapt to different screen sizes and devices. This ensures a seamless user experience across various platforms.![Different app body widths on a desktop and a mobile device.](/assets/apps/design-guidelines/layout/app-body-width.png)
App body width
App body widthThe following table shows recommended sizes for the app body width.
The Polaris Page component is an easy way to align the app body with the rest of the Shopify admin and make it simpler to update layouts over time.
Breakpoint | Default app body width | Behavior |
---|---|---|
xs | 0 – 489px | Flexible, always full width |
sm | 442px – 719px | Flexible, always full width |
md | 480px – 751px | Flexible, always full width |
lg | 752px – 950px | Flexible, then fixed width at 998px |
xl | 950px fixed | Fixed width |
![A full-width app body page, such as for a product list.](/assets/apps/design-guidelines/layout/full-width-page.png)
Tip
Use a full-width page when merchants are dealing with lists of data that have many columns.Full-width page
Anchor link to section titled "Full-width page"In some cases, it’s necessary to apply full width to the Polaris Page component. This includes single-column layouts with a high density of information in your app, such as product or order lists. Full-width pages only modify how the Page
component is displayed in lg
and xl
breakpoints.
The following sections explain when to use the default or full-width Page
component:
Layout options
Anchor link to section titled "Layout options"The Polaris Layout component offers various layouts to match the complexity of your app.
![Various layouts, including single and two-column.](/assets/apps/design-guidelines/layout/layout-options-intro.png)
Must Do
Keep your app aligned with the Shopify admin by using the Polaris Patterns for common layouts such as index pages and resource detail pages.Single-column layout
Anchor link to section titled "Single-column layout"The single-column layout enables merchants to scan content from top-to-bottom and focus on a single, obvious task.
Most often, an app’s homepage uses the single-column layout in a default-width page. However, if your app feels more like a dashboard, then you can also use the two-column equal width or three-column layout.
![An app home page in a single-column layout. The home page includes a product list.](/assets/apps/design-guidelines/layout/single-column-layout.png)
![A full-width page with a single column layout that displays a list of products. The width captures each column of product information.](/assets/apps/design-guidelines/layout/single-column-layout-full-width-correct.png)
Must Do
Use a full-width page when merchants are dealing with lists of data that have many columns.![A full-width page using a single column layout for content that doesn't require that amount of horizontal space, so it looks stretched out.](/assets/apps/design-guidelines/layout/single-column-layout-full-width-wrong.png)
Do Not
Don’t use a single-column layout with a full-width page when you’re not dealing with lists of data. This makes the app feel out of place on larger displays. Apps should feel integrated with the Shopify admin.Two-column layout
Anchor link to section titled "Two-column layout"Two-column layouts include primary/secondary and equal-width.
Primary/secondary: Meant for complex editors where the primary column is used for parent content, and the secondary column is used for child content.
Equal-width: Meant for scanning information that has the same level of importance, like in a dashboard.
![A content editor with a two column layout for editing multiple and related content types.](/assets/apps/design-guidelines/layout/two-columns-primary-secondary.png)
Must Do
Complex editors should use the two-column primary/secondary layout in a default-width page. This offers merchants a streamlined editing experience.![An app home page that uses a two-column layout. The content between columns is unrelated.](/assets/apps/design-guidelines/layout/two-columns-primary-secondary-homepage.png)
Do Not
Don’t use a two-column primary/secondary layout for your app home page and other pages that don’t require a parent/child relationship between different parts of the interface.![A page labeled "Analytics" that uses a primary/secondary layout to display a dashboard of app metrics.](/assets/apps/design-guidelines/layout/two-columns-equal-width-dashboard.png)
Must Do
If your app’s page behaves as a dashboard, then use a two-column equal width layout. Use a three-column layout for higher content density.![An app that uses a two-column layout in full width. The page has many unrelated content types, some of which are in the same row. The UI is dense and difficult to scan.](/assets/apps/design-guidelines/layout/two-columns-equal-width-fullwidth.png)
Do Not
Don’t use two-column layouts in full-width pages, because it makes your app’s content harder to parse on larger displays.Annotated layout
Anchor link to section titled "Annotated layout"Annotated layouts are the best choice for pages that are dense with settings.
Learn more about this layout in the Polaris App settings pattern.
![An annotated layout that's used in an editor, with a thinner column on the left with a title and description, and a wider column on the right with form elements.](/assets/apps/design-guidelines/layout/annotated-layout.png)
![An annotated layout that's used for non-editable content. The annotation also isn't relevant to actions that the user can take.](/assets/apps/design-guidelines/layout/annotated-not-editable.png)
Do Not
Don’t use annotated layouts for content that isn’t editable. Use a single-column layout instead.Three-column layout
Anchor link to section titled "Three-column layout"Three-column layouts are for complex pages only, like analytics content. Similar to two-column layouts, three-column layouts are used for scanning information that has the same level of importance.
Three-column layouts work well when merchants need to compare across related information types.
![A page with three columns of equal width, which forms a convenient layout for users to select different product options.](/assets/apps/design-guidelines/layout/three-column-layouts.png)
![A three-column layout in a full-width page. The page is labeled "Analytics" and provides app metrics.](/assets/apps/design-guidelines/layout/three-column-dashboard.png)
Must Do
Set three-column layouts in a full-width page when you’re using them for interfaces like dashboards and analytics.![A three-column layout that shows cards of unrelated content in the same row.](/assets/apps/design-guidelines/layout/three-column-unrelated.png)
Do Not
Don’t use three-column layouts to display unrelated content side by side, as it can confuse merchants. Use a single-column layout instead.Spacing helps your app maintain a pleasant experience by keeping interface components well-positioned with consistent visual rhythm.
For more information on spacing, visit the Polaris spacing guidelines.
![Components on a 4px spacing grid.](/assets/apps/design-guidelines/layout/spacing-4px.png)
The 4px
spacing grid
The Shopify admin is built on a 4px
spacing grid. Following this grid is a great way to offer a seamless app experience. You can use Polaris spacing tokens to achieve this.
Information density
Anchor link to section titled "Information density"The density of elements in a layout can greatly impact your app’s readability and usability.
Make your app efficient and easy to use by providing the right density at the right moment, for the right task.
![Low density and high density patterns.](/assets/apps/design-guidelines/layout/information-density-spacing.png)
Must Do
Use looser spacing for low-density layouts. Use tighter spacing for high-density layouts.![Various layouts with alternating amounts of information density on the same page.](/assets/apps/design-guidelines/layout/information-density-changing-midpage.png)
Do Not
Don't change information density within a single page, otherwise your app can feel disjointed.Containers
Anchor link to section titled "Containers"Most of an app’s content exists in containers. Containers compartmentalize content and create a natural hierarchy between parts of an interface.
![A page with various containers that are visually consistent with each other.](/assets/apps/design-guidelines/layout/containers-majority.png)
Must Do
Make the majority of your app’s content live in a container, such as a card. This creates visual structure and rhythm that helps merchants find information quickly.![A paragraph of text placed directly on the gray background of an app, outside of a container.](/assets/apps/design-guidelines/layout/containers-paragraphs-of-text.png)
Do Not
Don't place paragraphs of text directly on the background. This reduces legibility and makes scanning the page difficult for merchants.Using cards
Anchor link to section titled "Using cards"Cards structure your app’s content so that merchants can scan information easily. Cards act as containers and can be static or interactive.
The Polaris Card component provides an easy way to segment content, while still respecting Shopify’s App Design Guidelines.
![Multiple cards with varying contents that fit nicely together.](/assets/apps/design-guidelines/layout/cards-majority.png)
Must Do
Place your app’s content in a card-like container a majority of the time. Complex components or images aren’t necessarily required to be in a container.![A card with two CTAs. The primary CTA is a button that's labeled "Upload image" and the secondary one is a link that reads "View templates".](/assets/apps/design-guidelines/layout/cards-interactive-cta.png)
Must Do
Cards that offer interactivity, such as calls to action (CTAs) and buttons, should have at most one primary styled action.Using tables
Anchor link to section titled "Using tables"Tables are helpful for summarizing many object instances. Use the Polaris Data table component for relatively simple summaries, and the Index table when you have a lot of data to show.
Refer also to the Polaris Pattern for Resource index layout, when you are summarizing resource objects.
![A table featuring dropdown menus and text buttons.](/assets/apps/design-guidelines/layout/table-actions.png)