--- title: Grid description: >- The grid component organizes content in a matrix of rows and columns to create responsive page layouts. api_version: 2026-01 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/web-components/layout-and-structure/grid md: >- https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/web-components/layout-and-structure/grid.md --- # Grid The grid component organizes content in a matrix of rows and columns to create responsive page layouts. Use grid to build complex, multi-column layouts that adapt to different screen sizes and maintain consistent alignment. Grid follows the CSS grid layout pattern and supports flexible column configurations, gap spacing, and alignment properties for precise layout control. For simpler linear layouts (horizontal or vertical), use [stack](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/web-components/layout-and-structure/stack). For scrollable grids, wrap the grid in a [scroll box](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/web-components/layout-and-structure/scroll-box). ### Support Targets (29) ### Supported targets * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/order-summary#checkout-cart-line-list-) * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/order-summary#thank-you-cart-line-list-) * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/targets/thank-you/header#header-target) #### Use cases * **Multi-column layouts**: Arrange content in rows and columns with precise positioning that adapts to container or viewport size * **Spanning cells**: Let header or footer elements stretch across multiple columns or rows *** ## Properties Configure the following properties on the grid component. * **accessibilityLabel** **string** A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. Only use this when the element's content is not enough context for users using assistive technologies. * **accessibilityRole** **AccessibilityRole** **Default: 'generic'** Sets the semantic meaning of the component’s content. When set, the role will be used by assistive technologies to help users navigate the page. * **accessibilityVisibility** **'visible' | 'hidden' | 'exclusive'** **Default: 'visible'** Controls how the element is exposed to sighted users and to assistive technologies such as screen readers. * `visible`: The element is visible to all users (both sighted users and screen readers). * `hidden`: The element is visually visible but hidden from screen readers. Use this for decorative elements that don't provide meaningful information. * `exclusive`: The element is visually hidden but announced by screen readers. Use this for screen-reader-only content like skip links or additional context. * **alignContent** **MaybeResponsive\** **Default: '' - meaning no override** Controls how the grid's rows are distributed along the block (column) axis when there is extra space. Set to an empty string to use the default. * **alignItems** **MaybeResponsive\** **Default: '' - meaning no override** Aligns grid items along the block (column) axis. Set to an empty string to use the default. * **background** **'base' | 'subdued' | 'transparent'** **Default: 'transparent'** The background color of the grid. * `base`: The standard background color for general content areas. * `subdued`: A muted background for secondary or supporting content. * `transparent`: No background color (the default). * **blockSize** **MaybeResponsive\** **Default: 'auto'** The block size of the element (height in horizontal writing modes). Learn more about the [block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size). * `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. * `auto`: Automatically sizes based on content and layout constraints. * **border** **BorderShorthand** **Default: 'none'** A shorthand for setting the border width, color, and style in a single property. Individual border properties (`borderWidth`, `borderStyle`, `borderColor`) can override values set here. * **borderColor** **'' | 'base'** **Default: '' - meaning no override** The color of the border using the design system's color scale. Overrides the color value set by `border`. * **borderRadius** **MaybeAllValuesShorthandProperty\>** **Default: 'none'** The roundedness of the grid's corners. * `none`: Sharp corners with no rounding. * `small-100` / `small`: Subtle rounding for compact elements. * `base`: Standard rounding for most use cases. * `large` / `large-100`: More pronounced rounding for prominent containers. * `max`: Maximum rounding, creating a pill or circular shape. Supports 1-to-4-value shorthand syntax for specifying different radii per corner. * **borderStyle** **MaybeAllValuesShorthandProperty\ | ""** **Default: '' - meaning no override** Controls the visual style of the border on all sides, such as solid, dashed, or dotted. When set, this overrides the style value specified in the `border` property. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different styles per side: * One value: applies to all sides * Two values: applies to block sides (top/bottom) and inline sides (left/right) respectively * Three values: applies to block-start (top), inline sides (left/right), and block-end (bottom) respectively * Four values: applies to block-start (top), inline-end (right), block-end (bottom), and inline-start (left) respectively * **borderWidth** **MaybeAllValuesShorthandProperty\ | ''** **Default: '' - meaning no override** The thickness of the border on all sides. Supports 1-to-4-value shorthand syntax for specifying different widths per side. Overrides the width value set by `border`. * **columnGap** **MaybeResponsive\** **Default: '' - meaning no override** Adjust spacing between elements in the inline axis. This overrides the column value of `gap`. * **display** **MaybeResponsive<"auto" | "none">** **Default: 'auto'** Sets the outer display type of the component. The outer type sets a component’s participation in [flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flow_layout). * `auto`: the component’s initial value. The actual value depends on the component and context. * `none`: hides the component from display and removes it from the accessibility tree, making it invisible to screen readers. Learn more about the [display property](https://developer.mozilla.org/en-US/docs/Web/CSS/display). * **gap** **MaybeResponsive\>** **Default: 'none'** Adjust spacing between elements. A single value applies to both axes. A pair of values (eg `large-100 large-500`) can be used to set the inline and block axes respectively. * **gridTemplateColumns** **MaybeResponsive\** **Default: 'none'** Define columns and specify their size. * **gridTemplateRows** **MaybeResponsive\** **Default: 'none'** Define rows and specify their size. * **id** **string** A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting. * **inlineSize** **MaybeResponsive\** **Default: 'auto'** The inline size of the element (width in horizontal writing modes). Learn more about the [inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size). * `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. * `auto`: Automatically sizes based on content and layout constraints. * **justifyContent** **MaybeResponsive\** **Default: '' - meaning no override** Controls how the grid's columns are distributed along the inline (row) axis when there is extra space. Set to an empty string to use the default. * **justifyItems** **MaybeResponsive\** **Default: '' - meaning no override** Aligns grid items along the inline (row) axis. Set to an empty string to use the default. * **maxBlockSize** **MaybeResponsive\** **Default: 'none'** The maximum block size of the element (maximum height in horizontal writing modes). Learn more about the [max-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size). * **maxInlineSize** **MaybeResponsive\** **Default: 'none'** The maximum inline size of the element (maximum width in horizontal writing modes). Learn more about the [max-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size). * **minBlockSize** **MaybeResponsive\** **Default: '0'** The minimum block size of the element (minimum height in horizontal writing modes). Learn more about the [min-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size). * **minInlineSize** **MaybeResponsive\** **Default: '0'** The minimum inline size of the element (minimum width in horizontal writing modes). Learn more about the [min-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size). * **overflow** **'hidden' | 'visible'** **Default: 'visible'** Sets the overflow behavior of the element. * `visible`: The content that extends beyond the element’s container is visible. * `hidden`: Clips the content when it is larger than the element’s container. The element will not be scrollable and users will not be able to access the clipped content by dragging or using a scroll wheel on a mouse. * **padding** **MaybeResponsive\>** **Default: 'none'** The padding applied to all edges of the component. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) using flow-relative values: * 1 value applies to all sides * 2 values apply to block (top/bottom) and inline (left/right) * 3 values apply to block-start (top), inline (left/right), and block-end (bottom) * 4 values apply to block-start (top), inline-end (right), block-end (bottom), and inline-start (left) **Examples:** `base`, `large none`, `base large-100 base small` Use `auto` to inherit padding from the nearest container with removed padding. * **paddingBlock** **MaybeResponsive\ | "">** **Default: '' - meaning no override** The block-direction padding (top and bottom in horizontal writing modes). Accepts a single value for both sides or two space-separated values for block-start and block-end. **Example:** `large none` applies `large` to the top and `none` to the bottom. Overrides the block value from `padding`. * **paddingBlockEnd** **MaybeResponsive\** **Default: '' - meaning no override** The block-end padding (bottom in horizontal writing modes). Overrides the block-end value from `paddingBlock`. * **paddingBlockStart** **MaybeResponsive\** **Default: '' - meaning no override** The block-start padding (top in horizontal writing modes). Overrides the block-start value from `paddingBlock`. * **paddingInline** **MaybeResponsive\ | "">** **Default: '' - meaning no override** The inline-direction padding (left and right in horizontal writing modes). Accepts a single value for both sides or two space-separated values for inline-start and inline-end. **Example:** `large none` applies `large` to the left and `none` to the right. Overrides the inline value from `padding`. * **paddingInlineEnd** **MaybeResponsive\** **Default: '' - meaning no override** The inline-end padding (right in LTR writing modes, left in RTL). Overrides the inline-end value from `paddingInline`. * **paddingInlineStart** **MaybeResponsive\** **Default: '' - meaning no override** The inline-start padding (left in LTR writing modes, right in RTL). Overrides the inline-start value from `paddingInline`. * **placeContent** **MaybeResponsive<\`${ReducedAlignContentKeyword} ${ReducedJustifyContentKeyword}\` | ReducedAlignContentKeyword>** **Default: 'normal normal'** A shorthand for `justifyContent` and `alignContent` that sets both distribution axes at once. * **placeItems** **MaybeResponsive<\`${ReducedAlignItemsKeyword} ${ReducedJustifyItemsKeyword}\` | ReducedAlignItemsKeyword>** **Default: 'normal normal'** A shorthand for `justifyItems` and `alignItems` that sets both alignment axes at once. * **rowGap** **MaybeResponsive\** **Default: '' - meaning no override** Adjust spacing between elements in the block axis. This overrides the row value of `gap`. ### AccessibilityRole The semantic role of a component, used by assistive technologies to convey the element’s purpose to users. Each role maps to a specific HTML element or ARIA role. - \`main\`: The primary content of the page. - \`header\`: A page or section header. - \`footer\`: Information such as copyright, navigation links, and privacy statements. - \`section\`: A generic section that should have a heading or \`accessibilityLabel\`. - \`aside\`: Supporting content related to the main content. - \`navigation\`: A major group of navigation links. - \`ordered-list\`: A list of ordered items. - \`list-item\`: An item inside a list. - \`list-item-separator\`: A divider between list items. - \`unordered-list\`: A list of unordered items. - \`separator\`: A divider that separates sections of content. - \`status\`: A live region with advisory information that is not urgent. - \`alert\`: Important, usually time-sensitive information. - \`generic\`: A nameless container with no semantic meaning (renders a \`\
\`). - \`presentation\`: Strips semantic meaning while keeping visual styling. Synonym for \`none\`. - \`none\`: Strips semantic meaning while keeping visual styling. Synonym for \`presentation\`. ```ts "main" | "header" | "footer" | "section" | "aside" | "navigation" | "ordered-list" | "list-item" | "list-item-separator" | "unordered-list" | "separator" | "status" | "alert" | "generic" | "presentation" | "none" ``` ### MaybeResponsive Makes a property responsive by allowing it to be set conditionally based on container query conditions. The value can be either a base value or a container query string. - \`T\`: Base value that applies in all conditions. - \`@container${string}\`: Container query string for conditional responsive styling based on container size. ```ts T | `@container${string}` ``` ### ReducedAlignContentKeyword The subset of \`align-content\` values available for the grid component. - \`center\`: Packs rows toward the center of the grid. - \`start\`: Packs rows toward the start of the block axis. - \`end\`: Packs rows toward the end of the block axis. - \`normal\`: Default browser behavior. - \`space-between\`: Distributes rows evenly with no space at the edges. - \`space-around\`: Distributes rows evenly with equal space around each. - \`space-evenly\`: Distributes rows with equal space between and at the edges. - \`stretch\`: Stretches rows to fill the available space. ```ts 'center' | 'start' | 'end' | 'normal' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' ``` ### ReducedAlignItemsKeyword The subset of \`align-items\` values available for the grid component. - \`center\`: Centers items along the block axis. - \`start\`: Aligns items to the start of the block axis. - \`end\`: Aligns items to the end of the block axis. - \`normal\`: Default browser behavior. - \`baseline\`: Aligns items along their text baseline. - \`stretch\`: Stretches items to fill the cell along the block axis. ```ts 'center' | 'start' | 'end' | 'normal' | 'baseline' | 'stretch' ``` ### SizeUnitsOrAuto Represents size values that can also be set to \`auto\` for automatic sizing. - \`SizeUnits\`: Specific size values in pixels, percentages, or zero for precise control. - \`auto\`: Automatically sizes based on content and layout constraints. Learn more about the \[auto value]\(https://developer.mozilla.org/en-US/docs/Web/CSS/width#auto). ```ts SizeUnits | "auto" ``` ### SizeUnits Represents size values in pixels, percentages, or zero. - \`\` \`${number}px\` \`\`: Absolute size in pixels for fixed dimensions (such as \`100px\`, \`24px\`). - \`\` \`${number}%\` \`\`: Relative size as a percentage of the parent container (such as \`50%\`, \`100%\`). - \`0\`: Zero size, equivalent to no dimension. ```ts `${number}px` | `${number}%` | `0` ``` ### BorderShorthand A shorthand string for specifying border properties. Accepts a size alone (\`'base'\`), size with color (\`'base base'\`), or size with color and style (\`'base base dashed'\`). Omitted values use their defaults. ```ts ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}` ``` ### ReducedBorderSizeKeyword The subset of border size values available for this component. - \`base\`: Standard border width. - \`large\`: Thick border for strong emphasis. - \`large-100\`: Extra thick border for maximum prominence. - \`large-200\`: The thickest available border. - \`none\`: No border. ```ts 'large' | 'base' | 'large-100' | 'large-200' | 'none' ``` ### ReducedColorKeyword The subset of border color values available for this component. - \`base\`: The standard border color for most contexts. ```ts 'base' ``` ### BorderStyleKeyword The visual style of a border. Learn more about \[border-style]\(https://developer.mozilla.org/en-US/docs/Web/CSS/border-style). - \`none\`: No border is rendered. - \`solid\`: A single continuous line. - \`dashed\`: A series of short dashes. - \`dotted\`: A series of round dots. - \`auto\`: The border style is determined automatically based on the surface's design system. ```ts "none" | "solid" | "dashed" | "dotted" | "auto" ``` ### MaybeAllValuesShorthandProperty Represents CSS shorthand properties that accept one to four values, following the \[CSS shorthand syntax]\(https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand\_properties#edges\_of\_a\_box). Supports specifying values for all four sides: top, right, bottom, and left. - \`T\`: Single value that applies to all four sides. - \`${T} ${T}\`: Two values for block axis (top/bottom) and inline axis (left/right). - \`${T} ${T} ${T}\`: Three values for block-start (top), inline axis (left/right), and block-end (bottom). - \`${T} ${T} ${T} ${T}\`: Four values for block-start (top), inline-end (right), block-end (bottom), and inline-start (left). ```ts T | `${T} ${T}` | `${T} ${T} ${T}` | `${T} ${T} ${T} ${T}` ``` ### SpacingKeyword ```ts SizeKeyword | "none" ``` ### SizeKeyword The design system's size scale, used to control the dimensions of components like avatars, icons, and thumbnails. Values range from \`"small-500"\` (smallest) through \`"base"\` (standard) to \`"large-500"\` (largest). Not all components support every size — check the component's \`size\` property type for its available options. ```ts "small-500" | "small-400" | "small-300" | "small-200" | "small-100" | "small" | "base" | "large" | "large-100" | "large-200" | "large-300" | "large-400" | "large-500" ``` ### MaybeTwoValuesShorthandProperty Represents CSS shorthand properties that accept one or two values. Supports specifying the same value for both dimensions or different values. - \`T\`: Single value that applies to both dimensions. - \`${T} ${T}\`: Two values for block axis (vertical) and inline axis (horizontal). ```ts T | `${T} ${T}` ``` ### ReducedJustifyContentKeyword The subset of \`justify-content\` values available for the grid component. - \`center\`: Packs columns toward the center of the grid. - \`start\`: Packs columns toward the start of the inline axis. - \`end\`: Packs columns toward the end of the inline axis. - \`normal\`: Default browser behavior. - \`space-between\`: Distributes columns evenly with no space at the edges. - \`space-around\`: Distributes columns evenly with equal space around each. - \`space-evenly\`: Distributes columns with equal space between and at the edges. - \`stretch\`: Stretches columns to fill the available space. ```ts 'center' | 'start' | 'end' | 'normal' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch' ``` ### ReducedJustifyItemsKeyword The subset of \`justify-items\` values available for the grid component. - \`center\`: Centers items along the inline axis. - \`start\`: Aligns items to the start of the inline axis. - \`end\`: Aligns items to the end of the inline axis. - \`normal\`: Default browser behavior. - \`baseline\`: Aligns items along their text baseline. - \`stretch\`: Stretches items to fill the cell along the inline axis. ```ts 'center' | 'start' | 'end' | 'normal' | 'baseline' | 'stretch' ``` ### SizeUnitsOrNone Represents size values that can also be set to \`none\` to remove the size constraint. - \`SizeUnits\`: Specific size values in pixels, percentages, or zero for precise control. - \`none\`: No size constraint, allowing unlimited growth. Learn more about the \[none value]\(https://developer.mozilla.org/en-US/docs/Web/CSS/max-width#none). ```ts SizeUnits | "none" ``` ### PaddingKeyword Defines the padding size for elements, using the standard size scale or \`none\` for no padding. - \`SizeKeyword\`: Standard padding sizes from the size scale for consistent spacing. - \`none\`: No padding. ```ts SizeKeyword | "none" ``` *** ## Grid item The grid item component represents a single cell within a grid layout, allowing you to control how content is positioned and sized within the grid. Use grid item as a child of grid to specify column span, row span, and positioning for individual content areas. Grid item supports precise placement control through column and row properties, enabling you to create complex layouts where different items occupy varying amounts of space or appear in specific grid positions. * **accessibilityLabel** **string** A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. Only use this when the element's content is not enough context for users using assistive technologies. * **accessibilityRole** **AccessibilityRole** **Default: 'generic'** Sets the semantic meaning of the component’s content. When set, the role will be used by assistive technologies to help users navigate the page. * **accessibilityVisibility** **'visible' | 'hidden' | 'exclusive'** **Default: 'visible'** Controls how the element is exposed to sighted users and to assistive technologies such as screen readers. * `visible`: The element is visible to all users (both sighted users and screen readers). * `hidden`: The element is visually visible but hidden from screen readers. Use this for decorative elements that don't provide meaningful information. * `exclusive`: The element is visually hidden but announced by screen readers. Use this for screen-reader-only content like skip links or additional context. * **background** **'base' | 'subdued' | 'transparent'** **Default: 'transparent'** The background color of the grid item. * `base`: The standard background color for general content areas. * `subdued`: A muted background for secondary or supporting content. * `transparent`: No background color (the default). * **blockSize** **MaybeResponsive\** **Default: 'auto'** The block size of the element (height in horizontal writing modes). Learn more about the [block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size). * `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. * `auto`: Automatically sizes based on content and layout constraints. * **border** **BorderShorthand** **Default: 'none'** A shorthand for setting the border width, color, and style in a single property. Individual border properties (`borderWidth`, `borderStyle`, `borderColor`) can override values set here. * **borderColor** **'' | 'base'** **Default: '' - meaning no override** The color of the border using the design system's color scale. Overrides the color value set by `border`. * **borderRadius** **MaybeAllValuesShorthandProperty\>** **Default: 'none'** The roundedness of the grid item's corners. * `none`: Sharp corners with no rounding. * `small-100` / `small`: Subtle rounding for compact elements. * `base`: Standard rounding for most use cases. * `large` / `large-100`: More pronounced rounding for prominent containers. * `max`: Maximum rounding, creating a pill or circular shape. Supports 1-to-4-value shorthand syntax for specifying different radii per corner. * **borderStyle** **MaybeAllValuesShorthandProperty\ | ""** **Default: '' - meaning no override** Controls the visual style of the border on all sides, such as solid, dashed, or dotted. When set, this overrides the style value specified in the `border` property. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different styles per side: * One value: applies to all sides * Two values: applies to block sides (top/bottom) and inline sides (left/right) respectively * Three values: applies to block-start (top), inline sides (left/right), and block-end (bottom) respectively * Four values: applies to block-start (top), inline-end (right), block-end (bottom), and inline-start (left) respectively * **borderWidth** **MaybeAllValuesShorthandProperty\ | ''** **Default: '' - meaning no override** The thickness of the border on all sides. Supports 1-to-4-value shorthand syntax for specifying different widths per side. Overrides the width value set by `border`. * **display** **MaybeResponsive<"auto" | "none">** **Default: 'auto'** Sets the outer display type of the component. The outer type sets a component’s participation in [flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flow_layout). * `auto`: the component’s initial value. The actual value depends on the component and context. * `none`: hides the component from display and removes it from the accessibility tree, making it invisible to screen readers. Learn more about the [display property](https://developer.mozilla.org/en-US/docs/Web/CSS/display). * **gridColumn** **\`span ${number}\` | "auto"** **Default: 'auto'** Number of columns the item will span across * **gridRow** **\`span ${number}\` | "auto"** **Default: 'auto'** Number of rows the item will span across * **id** **string** A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting. * **inlineSize** **MaybeResponsive\** **Default: 'auto'** The inline size of the element (width in horizontal writing modes). Learn more about the [inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size). * `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. * `auto`: Automatically sizes based on content and layout constraints. * **maxBlockSize** **MaybeResponsive\** **Default: 'none'** The maximum block size of the element (maximum height in horizontal writing modes). Learn more about the [max-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size). * **maxInlineSize** **MaybeResponsive\** **Default: 'none'** The maximum inline size of the element (maximum width in horizontal writing modes). Learn more about the [max-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size). * **minBlockSize** **MaybeResponsive\** **Default: '0'** The minimum block size of the element (minimum height in horizontal writing modes). Learn more about the [min-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size). * **minInlineSize** **MaybeResponsive\** **Default: '0'** The minimum inline size of the element (minimum width in horizontal writing modes). Learn more about the [min-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size). * **overflow** **'hidden' | 'visible'** **Default: 'visible'** Sets the overflow behavior of the element. * `visible`: The content that extends beyond the element’s container is visible. * `hidden`: Clips the content when it is larger than the element’s container. The element will not be scrollable and users will not be able to access the clipped content by dragging or using a scroll wheel on a mouse. * **padding** **MaybeResponsive\>** **Default: 'none'** The padding applied to all edges of the component. Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) using flow-relative values: * 1 value applies to all sides * 2 values apply to block (top/bottom) and inline (left/right) * 3 values apply to block-start (top), inline (left/right), and block-end (bottom) * 4 values apply to block-start (top), inline-end (right), block-end (bottom), and inline-start (left) **Examples:** `base`, `large none`, `base large-100 base small` Use `auto` to inherit padding from the nearest container with removed padding. * **paddingBlock** **MaybeResponsive\ | "">** **Default: '' - meaning no override** The block-direction padding (top and bottom in horizontal writing modes). Accepts a single value for both sides or two space-separated values for block-start and block-end. **Example:** `large none` applies `large` to the top and `none` to the bottom. Overrides the block value from `padding`. * **paddingBlockEnd** **MaybeResponsive\** **Default: '' - meaning no override** The block-end padding (bottom in horizontal writing modes). Overrides the block-end value from `paddingBlock`. * **paddingBlockStart** **MaybeResponsive\** **Default: '' - meaning no override** The block-start padding (top in horizontal writing modes). Overrides the block-start value from `paddingBlock`. * **paddingInline** **MaybeResponsive\ | "">** **Default: '' - meaning no override** The inline-direction padding (left and right in horizontal writing modes). Accepts a single value for both sides or two space-separated values for inline-start and inline-end. **Example:** `large none` applies `large` to the left and `none` to the right. Overrides the inline value from `padding`. * **paddingInlineEnd** **MaybeResponsive\** **Default: '' - meaning no override** The inline-end padding (right in LTR writing modes, left in RTL). Overrides the inline-end value from `paddingInline`. * **paddingInlineStart** **MaybeResponsive\** **Default: '' - meaning no override** The inline-start padding (left in LTR writing modes, right in RTL). Overrides the inline-start value from `paddingInline`. *** ## Examples ### Create a two-column grid layout Arrange content in rows and columns using CSS grid. This example lays out a two-column `s-grid` with `gridTemplateColumns`, a header spanning both columns, and product rows below. ## Create a two-column grid layout ![A rendered example of the grid component](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/grid-default-yTqBGt_1.png) ## html ```html Plants for sale Pothos $25.00 ``` ### Center items in a two-column grid Align content on both axes inside a two-column grid. This example centers labels with `placeItems="center"` inside each cell. ## html ```html Item Qty ``` ### Build a responsive grid with container queries Switch between one and two columns based on container width. This example wraps `s-grid` in `s-query-container` and uses responsive `gridTemplateColumns` so narrow containers stack and wider ones split. ## html ```html Billing address Shipping address ``` *** ## Best practices * **Use grid for multi-column layouts**: Grid excels at two-dimensional layouts where you need rows and columns. For simple horizontal or vertical arrangements, use [stack](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/web-components/layout-and-structure/stack). * **Define explicit column templates**: Always set `gridTemplateColumns` so the layout is predictable. Flexible units like `1fr` and `auto` create responsive designs that adapt to content. * **Use grid items for spanning**: When a child needs to occupy multiple columns or rows, wrap it in `s-grid-item` and set `gridColumn` or `gridRow`. * **Keep gap spacing consistent**: Use the same `gap` value across grids in the same page for visual consistency. * **Pair with query containers**: Wrap grids in `s-query-container` when column counts should follow parent width, not the viewport alone. ***