Skip to main content
Upgrade to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use Polaris web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the upgrade guide to upgrade your extension and avoid being blocked from updating your extension after October 1st 2026.

Grid

The Grid component organizes content in a matrix of rows and columns to create structured page layouts. Use Grid to build complex, multi-column layouts that maintain consistent alignment, such as detail pages with label-value pairs or product comparison views.

Grid supports flexible column and row configurations, gap spacing, and alignment properties for precise layout control. For simpler one-dimensional layouts, use InlineLayout (columns) or BlockStack (rows).

Support
Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the Grid component.

Anchor to accessibilityLabel
accessibilityLabel
string

A label announced by assistive technologies that describes the purpose or contents of the element. Only set this when the element's visible content doesn't provide enough context on its own.

Anchor to accessibilityRole
accessibilityRole

The semantic meaning of the component's content. When set, assistive technologies use this role to help users navigate the page. Accepts a single role or a tuple of two roles (for example, ['listItem', 'separator']).

Anchor to background
background
<>
Default: 'transparent'

The background color of the element, set using a design-system keyword.

Anchor to blockAlignment
blockAlignment
<>

The alignment of children along the block (cross) axis.

Anchor to border
border
<<>>

The border style of the element. Accepts a single value for all four edges, or a shorthand tuple for per-edge control:

  • 'base': Applies base to all edges.
  • ['base', 'none']: Block edges get base, inline edges get none.
  • ['base', 'none', 'dotted', 'base']: Values apply to block-start, inline-end, block-end, and inline-start respectively.
Anchor to borderWidth
borderWidth
< <> >

The border width of the element. Accepts a single value for all four edges, or a shorthand tuple for per-edge control:

  • 'base': Applies base to all edges.
  • ['base', 'medium']: Block edges get base, inline edges get medium.
  • ['base', 'medium', 'medium', 'base']: Values apply to block-start, inline-end, block-end, and inline-start respectively.
Anchor to columns
columns
<>
Default: 'fill'

The sizes for each column of the grid.

  • auto: The intrinsic size of the content.
  • fill: Fills the remaining available space. When multiple columns use fill, the space is shared equally.
  • `${number}%`: A percentage of the container's inline size.
  • `${number}fr`: A fractional unit of the available space.
  • number: A fixed size in pixels.

When the sum of defined sizes exceeds the available space, elements shrink to avoid overflow (except inside a ScrollView). A single value outside an array creates one column of that size.

Anchor to cornerRadius
cornerRadius
< <> >

The corner radius of the element. Accepts a single value for all four corners, or a shorthand tuple for per-corner control using logical (writing-mode-aware) corners:

  • 'base': All four corners get base radius.
  • ['base', 'none']: StartStart/EndEnd get base, StartEnd/EndStart get none. In left-to-right mode, StartStart and EndEnd are the top-left and bottom-right corners.
  • ['base', 'none', 'small', 'base']: Values apply to StartStart, StartEnd, EndEnd, and EndStart respectively.

A borderRadius alias is available. When both are set, cornerRadius takes precedence.

Anchor to display
display
<'auto' | 'none'>
Default: 'auto'

The display mode of the component. Learn more about display.

  • auto: The initial value; the actual behavior depends on the component and context.
  • none: Hides the component and removes it from the accessibility tree.
Anchor to id
id
string

A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component.

Anchor to inlineAlignment
inlineAlignment
<>

The alignment of children along the inline (main) axis.

Anchor to maxBlockSize
maxBlockSize
< number | `${number}%` | 'fill' >

The maximum block size (maximum height in horizontal writing modes). The element won't grow taller than this value even if its content is longer.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's block size.
  • 'fill': Takes all the available space.

Learn more about the max-block-size property.

Anchor to maxInlineSize
maxInlineSize
< number | `${number}%` | 'fill' >

The maximum inline size (maximum width in horizontal writing modes). The element won't grow wider than this value.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's inline size.
  • 'fill': Takes all the available space.

Learn more about the max-inline-size property.

Anchor to minBlockSize
minBlockSize
< number | `${number}%` | 'fill' >

The minimum block size (minimum height in horizontal writing modes). The element won't shrink smaller than this value even if its content is shorter.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's block size.
  • 'fill': Takes all the available space.

Learn more about the min-block-size property.

Anchor to minInlineSize
minInlineSize
< number | `${number}%` | 'fill' >

The minimum inline size (minimum width in horizontal writing modes). The element won't shrink narrower than this value.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's inline size.
  • 'fill': Takes all the available space.

Learn more about the min-inline-size property.

Anchor to overflow
overflow
'hidden' | 'visible'
Default: 'visible'

The overflow behavior of the element.

  • visible: Content that extends beyond the container is visible.
  • hidden: Content that extends beyond the container is clipped and not scrollable.
Anchor to padding
padding
<<>>

The padding on all edges of the element, using a shorthand syntax. You can specify one, two, or four values following the CSS shorthand convention.

  • T: A single value applied uniformly to all edges.
  • [T, T]: The first value applies to block-start and block-end, the second to inline-start and inline-end.
  • [T, T, T, T]: Values apply to block-start, inline-end, block-end, and inline-start respectively.
Anchor to rows
rows
<>
Default: 'fill'

The sizes for each row of the grid.

  • auto: The intrinsic size of the content.
  • fill: Fills the remaining available space. When multiple rows use fill, the space is shared equally.
  • `${number}%`: A percentage of the container's block size.
  • `${number}fr`: A fractional unit of the available space.
  • number: A fixed size in pixels.

When the sum of defined sizes exceeds the available space, elements shrink to avoid overflow. A single value outside an array creates one row of that size.

Anchor to spacing
spacing
< | [, ]>
Default: 'none'

The spacing between child elements. A single value applies to both the row and column axes. A pair of values (for example, ['base', 'none']) sets the row and column spacing independently.

Anchor to borderRadius
borderRadius
< <> >

The corner radius of the element. Accepts a single value for all four corners, or a shorthand tuple for per-corner control:

  • 'base': All four corners get base radius.
  • ['base', 'none']: StartStart/EndEnd get base, StartEnd/EndStart get none.
  • ['base', 'none', 'small', 'base']: Values apply to StartStart, StartEnd, EndEnd, and EndStart respectively.
Deprecated

Use cornerRadius instead.

Anchor to ExamplesExamples

Anchor to Create a grid layoutCreate a grid layout

Use Grid with the columns prop to arrange content in a multi-column layout with consistent spacing. This example creates a grid with equally sized columns.

Create a grid layout

A Grid component arranging content in rows and columns.

Create a grid layout

import {
reactExtension,
Grid,
View,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<Grid
columns={['20%', 'fill', 'auto']}
rows={[300, 'auto']}
spacing="loose"
>
<View border="base" padding="base">
20% / 300
</View>
<View border="base" padding="base">
fill / 300
</View>
<View border="base" padding="base">
auto / 300
</View>
<View border="base" padding="base">
20% / auto
</View>
<View border="base" padding="base">
fill / auto
</View>
<View border="base" padding="base">
auto / auto
</View>
</Grid>
);
}
import {extension, Grid, View} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const grid = root.createComponent(
Grid,
{
columns: ['20%', 'fill', 'auto'],
rows: [300, 'auto'],
},
[
root.createComponent(
View,
{border: 'base', padding: 'base'},
'20% / 300',
),
root.createComponent(
View,
{border: 'base', padding: 'base'},
'fill / 300',
),
root.createComponent(
View,
{border: 'base', padding: 'base'},
'auto / 300',
),
root.createComponent(
View,
{border: 'base', padding: 'base'},
'20% / auto',
),
root.createComponent(
View,
{border: 'base', padding: 'base'},
'fill / auto',
),
root.createComponent(
View,
{border: 'base', padding: 'base'},
'auto / auto',
),
],
);

root.appendChild(grid);
});

Anchor to Best practicesBest practices

  • Use Grid for two-dimensional layouts: Grid excels at layouts where you need both rows and columns. For single-row or single-column arrangements, InlineLayout or BlockStack are simpler.
  • Define explicit column templates: Set the columns prop so the layout is predictable and adapts to content.
  • Use GridItem for spanning: When a child needs to span multiple columns or rows, wrap it in GridItem.
  • Keep gap spacing consistent: Use the same spacing value across grids on the same page for visual harmony.

Anchor to LimitationsLimitations

  • Grid children are placed in document order by default. Explicit placement requires wrapping children in GridItem.
  • Grid doesn't support subgrid. Nested grids are independent and don't inherit track sizes.
  • Column and row definitions are passed as arrays, not CSS grid syntax. Use StyleHelper for responsive values.
Was this page helpful?