Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.
GridItem
GridItem can be used as children of Grid.
It offers a way to span the element across a number of columns and rows.
Supported targets
- Checkout::Actions::Render
Before - Checkout::Cart
Line Details::Render After - Checkout::Cart
Lines::Render After - Checkout::Contact::Render
After - Checkout::Customer
Information::Render After - Checkout::Delivery
Address::Render Before - Checkout::Dynamic::Render
- Checkout::Pickup
Locations::Render After - Checkout::Pickup
Locations::Render Before - Checkout::Pickup
Points::Render After - Checkout::Pickup
Points::Render Before - Checkout::Reductions::Render
After - Checkout::Reductions::Render
Before - Checkout::Shipping
Method Details::Render After - Checkout::Shipping
Method Details::Render Expanded - Checkout::Shipping
Methods::Render After - Checkout::Shipping
Methods::Render Before - Checkout::Thank
You::Cart Line Details::Render After - Checkout::Thank
You::Cart Lines::Render After - Checkout::Thank
You::Customer Information::Render After - Checkout::Thank
You::Dynamic::Render - purchase.
checkout. actions. render-before - purchase.
checkout. block. render - purchase.
checkout. cart-line-item. render-after - purchase.
checkout. cart-line-list. render-after - purchase.
checkout. contact. render-after - purchase.
checkout. delivery-address. render-after - purchase.
checkout. delivery-address. render-before - purchase.
checkout. footer. render-after - purchase.
checkout. header. render-after - purchase.
checkout. payment-method-list. render-after - purchase.
checkout. payment-method-list. render-before - purchase.
checkout. pickup-location-list. render-after - purchase.
checkout. pickup-location-list. render-before - purchase.
checkout. pickup-location-option-item. render-after - purchase.
checkout. pickup-point-list. render-after - purchase.
checkout. pickup-point-list. render-before - purchase.
checkout. reductions. render-after - purchase.
checkout. reductions. render-before - purchase.
checkout. shipping-option-item. details. render - purchase.
checkout. shipping-option-item. render-after - purchase.
checkout. shipping-option-list. render-after - purchase.
checkout. shipping-option-list. render-before - purchase.
thank-you. announcement. render - purchase.
thank-you. block. render - purchase.
thank-you. cart-line-item. render-after - purchase.
thank-you. cart-line-list. render-after - purchase.
thank-you. customer-information. render-after - purchase.
thank-you. footer. render-after - purchase.
thank-you. header. render-after
Supported targets
- Checkout::Actions::Render
Before - Checkout::Cart
Line Details::Render After - Checkout::Cart
Lines::Render After - Checkout::Contact::Render
After - Checkout::Customer
Information::Render After - Checkout::Delivery
Address::Render Before - Checkout::Dynamic::Render
- Checkout::Pickup
Locations::Render After - Checkout::Pickup
Locations::Render Before - Checkout::Pickup
Points::Render After - Checkout::Pickup
Points::Render Before - Checkout::Reductions::Render
After - Checkout::Reductions::Render
Before - Checkout::Shipping
Method Details::Render After - Checkout::Shipping
Method Details::Render Expanded - Checkout::Shipping
Methods::Render After - Checkout::Shipping
Methods::Render Before - Checkout::Thank
You::Cart Line Details::Render After - Checkout::Thank
You::Cart Lines::Render After - Checkout::Thank
You::Customer Information::Render After - Checkout::Thank
You::Dynamic::Render - purchase.
checkout. actions. render-before - purchase.
checkout. block. render - purchase.
checkout. cart-line-item. render-after - purchase.
checkout. cart-line-list. render-after - purchase.
checkout. contact. render-after - purchase.
checkout. delivery-address. render-after - purchase.
checkout. delivery-address. render-before - purchase.
checkout. footer. render-after - purchase.
checkout. header. render-after - purchase.
checkout. payment-method-list. render-after - purchase.
checkout. payment-method-list. render-before - purchase.
checkout. pickup-location-list. render-after - purchase.
checkout. pickup-location-list. render-before - purchase.
checkout. pickup-location-option-item. render-after - purchase.
checkout. pickup-point-list. render-after - purchase.
checkout. pickup-point-list. render-before - purchase.
checkout. reductions. render-after - purchase.
checkout. reductions. render-before - purchase.
checkout. shipping-option-item. details. render - purchase.
checkout. shipping-option-item. render-after - purchase.
checkout. shipping-option-list. render-after - purchase.
checkout. shipping-option-list. render-before - purchase.
thank-you. announcement. render - purchase.
thank-you. block. render - purchase.
thank-you. cart-line-item. render-after - purchase.
thank-you. cart-line-list. render-after - purchase.
thank-you. customer-information. render-after - purchase.
thank-you. footer. render-after - purchase.
thank-you. header. render-after
Anchor to ExamplesExamples
Anchor to Basic GridItemBasic Grid
Basic GridItem
Basic GridItem
React
import {
reactExtension,
Grid,
GridItem,
View,
} from '@shopify/ui-extensions-react/checkout';
export default reactExtension(
'purchase.checkout.block.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>
<GridItem columnSpan={2}>
<View border="base" padding="base">
20% + fill / auto
</View>
</GridItem>
<View border="base" padding="base">
auto / auto
</View>
</Grid>
);
}JS
import {extension, Grid, GridItem, View} from '@shopify/ui-extensions/checkout';
export default extension('purchase.checkout.block.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(GridItem, {columnSpan: 2}, [
root.createComponent(
View,
{border: 'base', padding: 'base'},
'20% + fill / auto',
),
]),
root.createComponent(
View,
{border: 'base', padding: 'base'},
'auto / auto',
),
],
);
root.appendChild(grid);
});Anchor to PropertiesProperties
Anchor to griditempropsGridItemProps
- Anchor to accessibilityRoleaccessibilityRoleaccessibilityRoleViewLikeAccessibilityRoleViewLikeAccessibilityRole
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,
).- Anchor to backgroundbackgroundbackgroundMaybeConditionalStyle<Background>MaybeConditionalStyle<Background>Default: 'transparent'Default: 'transparent'
The background color of the element, set using a design-system keyword.
- Anchor to borderborderborderMaybeResponsiveConditionalStyle<MaybeShorthandProperty<BorderStyle>>MaybeResponsiveConditionalStyle<MaybeShorthandProperty<BorderStyle>>
The border style of the element. Accepts a single value for all four edges, or a shorthand tuple for per-edge control:
'base': Appliesbaseto all edges.['base', 'none']: Block edges getbase, inline edges getnone.['base', 'none', 'dotted', 'base']: Values apply to block-start, inline-end, block-end, and inline-start respectively.
- Anchor to borderWidthborderWidthborderWidthMaybeResponsiveConditionalStyle< MaybeShorthandProperty<BorderWidth> >MaybeResponsiveConditionalStyle< MaybeShorthandProperty<BorderWidth> >
The border width of the element. Accepts a single value for all four edges, or a shorthand tuple for per-edge control:
'base': Appliesbaseto all edges.['base', 'medium']: Block edges getbase, inline edges getmedium.['base', 'medium', 'medium', 'base']: Values apply to block-start, inline-end, block-end, and inline-start respectively.
- Anchor to columnSpancolumnSpancolumnSpanMaybeResponsiveConditionalStyle<number>MaybeResponsiveConditionalStyle<number>
The number of columns this item spans within the grid.
- Anchor to cornerRadiuscornerRadiuscornerRadiusMaybeResponsiveConditionalStyle< MaybeShorthandProperty<CornerRadius> >MaybeResponsiveConditionalStyle< MaybeShorthandProperty<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 getbaseradius.['base', 'none']: StartStart/EndEnd getbase, StartEnd/EndStart getnone. 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
alias is available. When both are set,takes precedence.- Anchor to displaydisplaydisplayMaybeResponsiveConditionalStyle<'auto' | 'none'>MaybeResponsiveConditionalStyle<'auto' | 'none'>Default: 'auto'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 idididstringstring
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 maxBlockSizemaxBlockSizemaxBlockSizeMaybeResponsiveConditionalStyle< number | `${number}%` | 'fill' >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 property.
- Anchor to maxInlineSizemaxInlineSizemaxInlineSizeMaybeResponsiveConditionalStyle< number | `${number}%` | 'fill' >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 property.
- Anchor to minBlockSizeminBlockSizeminBlockSizeMaybeResponsiveConditionalStyle< number | `${number}%` | 'fill' >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 property.
- Anchor to minInlineSizeminInlineSizeminInlineSizeMaybeResponsiveConditionalStyle< number | `${number}%` | 'fill' >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 property.
- Anchor to overflowoverflowoverflow'hidden' | 'visible''hidden' | 'visible'Default: '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 paddingpaddingpaddingMaybeResponsiveConditionalStyle<MaybeShorthandProperty<Spacing>>MaybeResponsiveConditionalStyle<MaybeShorthandProperty<Spacing>>
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 rowSpanrowSpanrowSpanMaybeResponsiveConditionalStyle<number>MaybeResponsiveConditionalStyle<number>
The number of rows this item spans within the grid.
- Anchor to borderRadiusborderRadiusborderRadiusMaybeResponsiveConditionalStyle< MaybeShorthandProperty<CornerRadius> >MaybeResponsiveConditionalStyle< MaybeShorthandProperty<CornerRadius> >deprecateddeprecated
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 getbaseradius.['base', 'none']: StartStart/EndEnd getbase, StartEnd/EndStart getnone.['base', 'none', 'small', 'base']: Values apply to StartStart, StartEnd, EndEnd, and EndStart respectively.
DeprecatedUse
instead.Deprecated:Use
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 `<li role='separator'>`).
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.
'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.
T | ConditionalStyle<T, AcceptedConditions>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.
ConditionalValue<T, AcceptedConditions>[] - default
The default value applied when none of the conditional values specified in `conditionals` are met.
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.
AcceptedConditions - value
The value that will be applied if the conditions are met.
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.
'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.
T | ConditionalStyle<T, ViewportSizeCondition>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.
{ min: T; }
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.
T | ShorthandProperty<T>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.
[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.
'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.
'base' | 'small' | 'large' | 'fullyRounded' | 'none' | CornerRadiusDeprecatedCornerRadiusDeprecated
'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.
'base' | 'medium' | 'thick'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.
'none' | 'extraTight' | 'tight' | 'base' | 'loose' | 'extraLoose'Anchor to Accessibility rolesAccessibility roles
| Value | Description |
|---|---|
"main" | Used to indicate the primary content. |
"header" | Used to indicate the component is a header. |
"footer" | Used to display information such as copyright information, navigation links, and privacy statements. |
"section" | Used to indicate a generic section. |
"complementary" | Used to designate a supporting section that relates to the main content. |
"navigation" | Used to identify major groups of links used for navigating. |
"orderedList" | Used to identify a list of ordered items. |
"listItem" | Used to identify an item inside a list of items. |
"unorderedList" | Used to identify a list of unordered items. |
"separator" | Used to indicates the component acts as a divider that separates and distinguishes sections of content. |
"status" | Used to define a live region containing advisory information for the user that is not important enough to be an alert. |
"alert" | Used for important, and usually time-sensitive, information. |
