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 the merchant's experience when using your app.

image of the responsive layout grid

Apps need to be built responsively so that they work on all device sizes. 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
xs 0 559px
sm 560px 767px
md 768px 1007px
lg 1008px 1775px
xl 1776px
image of different App Body widths on a desktop and mobile device

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 998px
xl 998px Fixed width
image of a full-width page, like a product list

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:

The Polaris Layout component offers various layouts to match the complexity of your app.

image of various layouts

The single-column layout enables merchants to scan content quickly and focus on a single, obvious task by offering a linear, top-to-bottom experience.

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.

image of an app home page in a single column layout
image of a page with a list

Mandatory

Use the single-column layout in a full-width page for pages where merchants deal with lists of data, such as product lists.
image of a page that has a stretched out single column layout

Unacceptable

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 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.

image of a content editor with multiple editable content types

Mandatory

Complex editors should use the two-column primary/secondary layout in a default-width page. This offers a streamlined editing experience for merchants.
image of an App home page with 2 column layout

Unacceptable

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.
image of a dashboard using a primary/secondary layout

Mandatory

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.
image of an App using 2 column layout in full width

Unacceptable

Don't use two-column layouts in full-width pages, because it makes your app's content harder to parse on larger displays.

Annotated layouts are the best choice for pages that are dense with settings.

image of an annotated layout 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

Tip

To keep your app aligned with the Shopify admin, use an annotated layout for editing settings or simple data.

image of annotated layout used for non-editable content

Unacceptable

Don't use annotated layouts for content that isn't editable. Use a single-column layout instead.

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.

image of a page with three columns of equal widths forming a layout
image of a three column layout in a full-width page

Mandatory

Set three-column layouts in a full-width page when you're using them for interfaces like dashboards and analytics.
image of a three column layout stacking

Caution

To preserve space for content, three-column layouts start stacking earlier than other layouts.
image of a three column layout that shows cards of unrelated content in the same row

Unacceptable

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.

image of components on a 4px spacing grid

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.

image of an altered component with spacing that doesn't align on a 4px grid

Caution

Altering a component's default spacing can make it look different from the Shopify admin, causing your app to feel disjointed.
image of a broken component with uneven spacing

Unacceptable

Don't use uneven spacing or visually jarring elements in your app. Instead, allow ample spacing to reduce visual clutter.

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.

image of a low density and high density patterns

Mandatory

Use looser spacing for low-density layouts. Use tighter spacing for high-density layouts.
image of an overloaded interface with a lot of small components

Caution

Too many elements on a page can cause visual clutter. Communicate more clearly with fewer elements.
image of various layouts with alternating amounts of  information density on the same page

Caution

Be careful when you're changing information density mid-page, otherwise your app can feel disjointed.

Most of an app's content exists in containers. Containers compartmentalize content and create a natural hierarchy between parts of an interface.

image of a page with various containers that are visually consistent with each other

Mandatory

Make 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.
image of a page where every little bit of text is contained within a card, causing visual clutter

Caution

Sometimes, card containers are unnecessary and create visual clutter, like when they're used to add subtitles or annotations.
image of a paragraph on text placed directly on the gray background of an App, outside of a container

Unacceptable

Don't place long content, such as paragraphs of text, directly on the background. This reduces legibility and makes scanning the page difficult for merchants.

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.

image of multiple cards with varying contents that fit nicely together

Mandatory

Place your app's content in a card-like container a majority of the time. However, complex components or images aren't necessarily required to be in a container.
image of multiple cards with similar content that are combined to form one bigger card that encompasses all related content together

Mandatory

Combine cards that are related to one another in terms of content when possible.
image of a card with two CTAs, some primary and another one, more subtle and secondary

Mandatory

Cards that offer interactivity, such as calls to action (CTAs) and buttons, should have one primary action and one secondary action.
image of a card with too many CTAs with different, jarring colors

Unacceptable

Avoid putting multiple CTAs or buttons that result in different actions on a single card. Instead, split each action into its own card.