Consistent spacing creates visual balance that makes the user interface (UI) easier for merchants to scan. Apply consistent spacing to improve the quality of the UI.

The spacing system

All spacing for components and typography is done in increments of 4 pixels. This 4px value forms the basic unit of measurement for spacing.

Small-screen view of the Shopify admin, showing a 4px grid and how spacing of various components line up

Typography doesn’t use a traditional baseline grid. Instead, line heights are set in increments of 4px and spacing is measured from the edges of the text boxes.

The Shopify admin, showing text bounding boxes and their alignment with a basic 4px grid

Many components are sized in increments of 20px to match the line height of body text. This makes it easy to create harmonious arrangements of components and text.

For example, the standard sizes of the avatar component have been chosen match the line height of body text:

A list item component with an avatar on the left, lining up with several rows of text on the right

Spacing in code

You can apply spacing in code in several ways:

  • Using stylesheets
  • Using utility components provided by Polaris React

Applying spacing with stylesheets

If you’re using Polaris with plain CSS, set values in increments of 4px. If you’re using Polaris’ built-in Sass library, you can use rem units or access common values via the spacing function.

CSS Sass (rem function) Sass (spacing function)
0 0 spacing(none)
4px rem(4px) spacing(extra-tight)
8px rem(8px) spacing(tight)
12px rem(12px)
16px rem(16px) spacing()
20px rem(20px) spacing(loose)
32px rem(32px) spacing(extra-loose)

Applying spacing with components

Text container

Use the text container component to wrap and automatically add the correct spacing between a set of paragraphs, lists, or other textual components.

Several paragraphs of text with space in between, with their edges and spacing highlighted


The stack component can be used to arrange arbitrary components in a horizontal row or vertical stack with space in between.

It accepts the same values as the Sass spacing function to control spacing between the items.

A text label, text value and badge arranged in a row, with their edges and spacing highlighted

How to choose spacing

Use less space between small components, or components that share a close functional relationship.

Two text fields showing spacing within and between them

Use more space between large components, or between components which are less functionally related.

Detail of a screen from Shopify admin, showing space between the page header and cards, between the cards, and the space around the layout

Coordinate small and large values, along with structural components like cards, to create visual groupings of related things. This helps merchants understand the interface and find what they’re looking for.

For screens with specialized layouts, adjust overall spacing based on the density of the content. For example, a simple login screen on desktop display has more room to breathe, so more space can be used.

Common values

4px (extra-tight) between icon and text

The button component has this spacing built in.

Space between icon and text in buttons and list items

8px (tight) between buttons

The button group component has this spacing built in.

Two buttons in a row, with annotation showing the space between

16 or 20px between form fields:

16px (base) vertically

20px (loose) horizontally

The form layout component has this spacing built in.

A form showing horizontal and vertical space between text fields

20px (loose) padding in cards

16px (base) side padding on small screen

The card component has this built in.

Detail of a card component from a large screen display, showing padding on the top, sides and between card sections

Detail of a card on a small screen, showing reduced side padding

20px (loose) between cards

The card component automatically adds vertical space between it and any preceding card.

For horizontal spacing, use the layout component to create multi-column layouts.

Detail of a screen from the Shopify admin, showing horizontal and vertical spacing between cards


When text is vertically centered inside a component, the top and bottom padding can be any size.

Closeup of a badge component, showing how its internal padding can be arbitrary, but its height is a multiple of 4px and the text within is vertically centered

The side padding within pill shapes can also be an odd number to match the shape’s radius.

Closeup of a badge component, showing how the rounded end of the badge results in an odd amound of side padding

Allow the length of text to determine the width of components and where they fall horizontally when placed in a row.

Three buttons in a row, showing how their width depends on their text content

Optical adjustment

Sometimes an element is larger than it appears. Spacing based on the invisible edges of the element will feel wrong. Correct for these optical effects by adjusting the space in 4px increments until it looks more balanced.

Without optical adjustment, the disclosure icon appears too far from the right edge of the button.

Diagram of a button with a disclosure triangle, without optical adjustment for the icon

After optical correction, the perceived spacing is more balanced.

Diagram of a button with optical adjustment for an icon