PolarisLayout
Polaris layout components let you quickly build custom layouts without writing CSS code.
What are layout components?
Polaris layout components define the structure and spacing of user interfaces in a fast and composable way. They create consistent layouts across all components and pages of an application. Developers can use these components to quickly create flexible pages and features without worrying about the underlying structure or CSS code.
Each layout component encapsulates CSS styles commonly found in the Shopify admin. Passing different values to the component props will render different CSS styles.
You can browse all layout and structure components, as well as view usage guidelines and examples for each component.
Layout components vs writing CSS
Polaris layout components provide several benefits over writing layout CSS code:
- Consistency. Layout components suggest standard layout and spacing, unifying the Shopify admin experience.
- Reusability. Create new pages and components with these layout building blocks, and avoid rewriting the same CSS code.
- Maintainability. CSS code is abstracted away, simplifying how you update layout and spacing. There’s also reduced risk of errors and breaking styles.
- Reliability. Reducing redundant CSS through layout components improves site performance for merchants.
- Faster development. Stop writing CSS code from scratch, and focus on the logic and functionality of your application.
Guiding behaviors
Layout components are intended to solve about 80% of layout use cases. But they won’t solve everything. For unique cases, leverage Polaris design tokens to write your own CSS styles. When building with layout components, keep the following behaviors and limitations in mind.
- Layout components are single purpose, composable, and flexible. Single-purpose components allow us to separate concerns and predict behavior when the design system changes. A known tradeoff can be extra elements in the markup.
Combine these components to build any layout. Their flexibility means different combinations can achieve the same visual result.
- Layout components shouldn’t affect anything outside of their borders. They should only impact components rendered inside of them. The exception is the Bleed component.
- Layout components have a default spacing of 0. There isn’t a perfect default, so add spacing with intention. For more information, refer to the Space guide.
- Layout component behaviors rely on Polaris tokens. Behaviors like spacing, color, and breakpoints are configured via component prop APIs. Each prop expects a specific value that maps to a Polaris design token.
Breakpoints and spacing
All layout components use the breakpoint scale and tokens. Consequently, consider how spacing can affect a layout, depending on screen size. On smaller screens, elements will be tighter. On medium to large screens, cards will be side by side and have more room.
To ensure designs are responsive, reference the breakpoints and examples in the Polaris Space documentation.
Layout component examples
The following examples illustrate how the new layout components can be composed together to create admin UI elements. Each example is just one approach to building that particular UI, but many other combinations of layout components can result in the same outcome. To get more comfortable, follow along with the video walkthroughs or try rebuilding these same UIs using a different combination of layout components.
Example 1
Admin UI card with a horizontal dot button on one side, plus text and a button on the opposite side. Edit in sandbox.
Example 2
Admin UI card with stacked elements, inline links, and a divider. Edit in sandbox.
Example 3
Admin UI card with text on one side, and a button on the opposite side. Edit in sanbox.
