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 the merchant’s experience when using your app.
Responsive layout gridAnchor 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 building your app:
|Breakpoint||Minimum viewport size||Maximum viewport size|
MandatoryApps need to be built responsively so that they work on all device sizes.
App body widthApp body width
The 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 – 502px||Flexible, always full width|
|sm||502px – 710px||Flexible, always full width|
|md||470px – 710px||Flexible, always full width|
|lg||710px – 998px||Flexible, then fixed width at
Full-width pageAnchor 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
The following sections explain when to use the default or full-width
Layout optionsAnchor link to section titled "Layout options"
The Polaris Layout component offers various layouts to match the complexity of your app.
Single-column layoutAnchor 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 the two-column equal width or three-column layout can also be used.
MandatoryUse a full-width page when merchants are dealing with lists of data that have many columns.
UnacceptableDon’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 layoutAnchor 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.
MandatoryComplex editors should use the two-column primary/secondary layout in a default-width page. This offers a streamlined editing experience for merchants.
UnacceptableDon’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.
MandatoryIf 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.
UnacceptableDon’t use two-column layouts in full-width pages, because it makes your app’s content harder to parse on larger displays.
Annotated layoutAnchor 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.
To keep your app aligned with the Shopify admin, use an annotated layout for editing settings or simple data.
UnacceptableDon’t use annotated layouts for content that isn’t editable. Use a single-column layout instead.
Three-column layoutAnchor 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.
MandatorySet three-column layouts in a full-width page when you’re using them for interfaces like dashboards and analytics.
CautionTo preserve space for content, three-column layouts start stacking earlier than other layouts.
UnacceptableDon’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.
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.
CautionAltering a component’s default spacing can make it look different from the Shopify admin, causing your app to feel disjointed.
UnacceptableDon’t use uneven spacing or visually jarring elements in your app. Instead, allow ample spacing to reduce visual clutter.
Information densityAnchor 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.
MandatoryUse looser spacing for low-density layouts. Use tighter spacing for high-density layouts.
CautionToo many elements on a page can cause visual clutter. Communicate more clearly with fewer elements.
CautionBe careful when you’re changing information density mid-page, otherwise your app can feel disjointed.
ContainersAnchor 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.
MandatoryMake the majority of your app’s content live in a container, like a card. This creates visual structure and rhythm that helps merchants find information quickly.
CautionSometimes, card containers are unnecessary and create visual clutter, like when they’re used to add subtitles or annotations.
UnacceptableDon’t place long content, such as paragraphs of text, directly on the background. This reduces legibility and makes scanning the page difficult for merchants.
Using cardsAnchor 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.