--- title: Grid description: >- 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. api_version: 2025-07 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/grid md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/grid.md --- Migrate to Polaris Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension. # 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](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/inlinelayout) (columns) or [BlockStack](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/blockstack) (rows). ### Support Targets (25) ### Supported targets * Customer​Account::Kitchen​Sink * [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-) * [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets) * [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-) * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-) * [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-) * [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets) * [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-) * [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-) * [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-) * [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-) * [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-) * [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-) * [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-) * [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-) * [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-) * [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-) * [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-) * customer-account.​profile.​payment.​render-after #### Use cases * **Order line items**: Display product names alongside prices in a two-column grid for clear, scannable order summaries. * **Account dashboards**: Arrange multiple information cards in a multi-column layout. * **Detail pages**: Pair labels with values in a consistent grid for shipping addresses, payment methods, or subscription details. * **Responsive layouts**: Use [StyleHelper](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/stylehelper) with Grid to change column counts at different viewport sizes. *** ## Properties Configure the following properties on the Grid component. * **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. * **accessibilityRole** **ViewLikeAccessibilityRole** 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']`). * **background** **MaybeConditionalStyle\** **Default: 'transparent'** The background color of the element, set using a design-system keyword. * **blockAlignment** **MaybeResponsiveConditionalStyle\** The alignment of children along the block (cross) axis. * **border** **MaybeResponsiveConditionalStyle\>** 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. * **borderWidth** **MaybeResponsiveConditionalStyle< MaybeShorthandProperty\ >** 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. * **columns** **MaybeResponsiveConditionalStyle\** **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. * **cornerRadius** **MaybeResponsiveConditionalStyle< MaybeShorthandProperty\ >** 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. * **display** **MaybeResponsiveConditionalStyle<'auto' | 'none'>** **Default: 'auto'** The display mode of the component. Learn more about [`display`](https://developer.mozilla.org/en-US/docs/Web/CSS/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. * **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. * **inlineAlignment** **MaybeResponsiveConditionalStyle\** The alignment of children along the inline (main) axis. * **maxBlockSize** **MaybeResponsiveConditionalStyle< 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](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size) property. * **maxInlineSize** **MaybeResponsiveConditionalStyle< 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](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size) property. * **minBlockSize** **MaybeResponsiveConditionalStyle< 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](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size) property. * **minInlineSize** **MaybeResponsiveConditionalStyle< 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](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size) property. * **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. * **padding** **MaybeResponsiveConditionalStyle\>** 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. * **rows** **MaybeResponsiveConditionalStyle\** **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. * **spacing** **MaybeResponsiveConditionalStyle\** **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. * **borderRadius** **MaybeResponsiveConditionalStyle< MaybeShorthandProperty\ >** **deprecated** 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. ### ViewLikeAccessibilityRole The accessibility role accepted by view-like layout components. Accepts a single \`NonPresentationalAccessibilityRole\`, or a tuple of two roles to combine semantic meaning (for example, \`\['listItem', 'separator']\` renders as \`\
  • \`). ```ts NonPresentationalAccessibilityRole | [NonPresentationalAccessibilityRole, NonPresentationalAccessibilityRole] ``` ### NonPresentationalAccessibilityRole The subset of accessibility roles available to layout components. Excludes \`decorative\` and \`presentation\`, which are only available on the full \`AccessibilityRole\` type. - \`main\`: The primary content of the page. - \`header\`: A page or section header. - \`footer\`: A section for copyright information, navigation links, and privacy statements. - \`section\`: A generic section; should have a heading or accessible label. - \`complementary\`: A supporting section related to the main content. - \`navigation\`: A major group of navigation links. - \`orderedList\`: A list of ordered items. - \`listItem\`: An item inside a list. - \`unorderedList\`: A list of unordered items. - \`separator\`: A divider separating sections of content. - \`status\`: A live region with advisory information that isn't urgent enough to be an alert. - \`alert\`: Important, usually time-sensitive information. ```ts 'main' | 'header' | 'footer' | 'section' | 'complementary' | 'navigation' | 'orderedList' | 'listItem' | 'unorderedList' | 'separator' | 'status' | 'alert' ``` ### MaybeConditionalStyle A type that represents a value that can be a conditional style. We highly recommend using the \`Style\` helper which simplifies the creation of conditional styles. ```ts T | ConditionalStyle ``` ### ConditionalStyle A conditional style definition that maps one or more conditions to different values. The \`default\` value is used as a fallback when none of the conditions in \`conditionals\` are satisfied. * conditionals An array of conditional values. ```ts ConditionalValue[] ``` * default The default value applied when none of the conditional values specified in \`conditionals\` are met. ```ts T ``` ### ConditionalValue A single conditional branch that pairs a set of conditions with the value to apply when those conditions are met. * conditions The conditions that must be met for the value to be applied. At least one condition must be specified. ```ts AcceptedConditions ``` * value The value that will be applied if the conditions are met. ```ts T ``` ### Background A keyword that maps to a predefined background color from the design system. - \`transparent\`: No background color; the parent's background shows through. - \`base\`: The standard surface background color. - \`subdued\`: A muted background color, typically used to de-emphasize content or distinguish secondary areas from the primary surface. ```ts 'transparent' | 'base' | 'subdued' ``` ### MaybeResponsiveConditionalStyle A type that represents a value that can be a conditional style. The conditions are based on the viewport size. We highly recommend using the \`Style\` helper which simplifies the creation of conditional styles. ```ts T | ConditionalStyle ``` ### ViewportSizeCondition A condition that targets layouts based on the inline size (width in horizontal writing modes) of the viewport. * viewportInlineSize The minimum viewport inline size that the condition must match. ```ts { min: T; } ``` ### BlockAlignment Controls how content is aligned along the block axis (vertical in standard writing modes). - \`'start'\`: Aligns content to the block start of the container. - \`'center'\`: Centers content along the block axis. - \`'end'\`: Aligns content to the block end of the container. - \`'baseline'\`: Aligns content so their text baselines line up. ```ts Alignment | 'baseline' ``` ### Alignment Controls how content is aligned along the cross axis. - \`'start'\`: Aligns content to the start of the container. - \`'center'\`: Centers content within the container. - \`'end'\`: Aligns content to the end of the container. ```ts 'start' | 'center' | 'end' ``` ### MaybeShorthandProperty A type that accepts either a single value applied to all edges or a shorthand tuple for per-edge control. - \`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. ```ts T | ShorthandProperty ``` ### ShorthandProperty A tuple type that accepts two or four values following the CSS shorthand convention for box 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. ```ts [T, T] | [T, T, T, T] ``` ### BorderStyle A keyword that maps to a predefined border style from the design system. - \`base\`: A solid border line, suitable for most use cases. - \`dashed\`: A dashed border line, often used for drop zones or placeholder boundaries. - \`dotted\`: A dotted border line. - \`none\`: No border is rendered. ```ts 'base' | 'dashed' | 'dotted' | 'none' ``` ### CornerRadius A keyword that maps to a predefined corner radius from the design system. - \`base\`: The default corner radius. - \`small\`: A subtle corner radius, smaller than \`base\`. - \`large\`: A pronounced corner radius, larger than \`base\`. - \`fullyRounded\`: Fully rounds the corners into a pill or circle shape. - \`none\`: No corner rounding; sharp square corners. ```ts 'base' | 'small' | 'large' | 'fullyRounded' | 'none' | CornerRadiusDeprecated ``` ### CornerRadiusDeprecated ```ts 'tight' | 'loose' ``` ### BorderWidth A keyword that maps to a predefined border width from the design system. - \`base\`: The default border width. - \`medium\`: A medium border width, thicker than \`base\`. - \`thick\`: The thickest available border width. ```ts 'base' | 'medium' | 'thick' ``` ### Columns The column sizing configuration for a grid-based layout. Accepts a single \`GridItemSize\` applied to all columns, or an array with one size per column. ```ts GridItemSize[] | GridItemSize ``` ### GridItemSize The size of a column or row in a grid-based layout. - \`'auto'\`: The intrinsic size of the content. - \`'fill'\`: Fills the remaining available space. When multiple items use \`fill\`, the space is shared equally. - \`number\`: A fixed size in pixels. - \`\` \`${number}fr\` \`\`: A fractional unit of the available space. - \`\` \`${number}%\` \`\`: A percentage of the container's size. ```ts 'auto' | 'fill' | number | `${number}fr` | `${number}%` ``` ### InlineAlignment Controls how content is aligned along the inline axis (horizontal in standard writing modes). - \`'start'\`: Aligns content to the inline start of the container. - \`'center'\`: Centers content along the inline axis. - \`'end'\`: Aligns content to the inline end of the container. ```ts 'start' | 'center' | 'end' ``` ### Spacing A keyword that maps to a predefined spacing value from the design system. Use these instead of pixel values to ensure consistent spacing throughout the UI. - \`none\`: No spacing (0px). - \`extraTight\`: The smallest amount of spacing. - \`tight\`: A compact amount of spacing, suitable for tight layouts. - \`base\`: The default spacing, appropriate for most layouts. - \`loose\`: A generous amount of spacing, used to create visual separation. - \`extraLoose\`: The largest amount of spacing. ```ts 'none' | 'extraTight' | 'tight' | 'base' | 'loose' | 'extraLoose' ``` ### Rows The row sizing configuration for a grid-based layout. Accepts a single \`GridItemSize\` applied to all rows, or an array with one size per row. ```ts GridItemSize[] | GridItemSize ``` *** ## Examples ### Create 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.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-07/grid-default-BaVM6b0U.png) ## Create a grid layout ##### React ```tsx import { reactExtension, Grid, View, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ( 20% / 300 fill / 300 auto / 300 20% / auto fill / auto auto / auto ); } ``` ##### JS ```js 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); }); ``` *** ## Best 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](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/inlinelayout) or [BlockStack](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/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](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/griditem). * **Keep gap spacing consistent**: Use the same `spacing` value across grids on the same page for visual harmony. *** ## Limitations * Grid children are placed in document order by default. Explicit placement requires wrapping children in [GridItem](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/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](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/stylehelper) for responsive values. ***