--- title: BlockLayout description: >- The BlockLayout component arranges content over multiple rows with explicit control over row sizing. Use BlockLayout to create vertical layouts where each row can have a different proportion, such as a fixed header row with an expandable content area below. 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/blocklayout md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/blocklayout.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. # BlockLayout The BlockLayout component arranges content over multiple rows with explicit control over row sizing. Use BlockLayout to create vertical layouts where each row can have a different proportion, such as a fixed header row with an expandable content area below. BlockLayout supports flexible row configurations and gap spacing for precise vertical layout control. For simpler vertical stacking with uniform spacing, use [BlockStack](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/blockstack). For horizontal column layouts, use [InlineLayout](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/inlinelayout). ### 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 * **Multi-row forms**: Arrange form fields in distinct rows with controlled sizing, such as a contact form with differently-sized input groups. * **Dashboard layouts**: Stack content blocks of varying heights in a vertical layout where each row can be explicitly sized. * **Order detail sections**: Lay out order summary, shipping details, and payment information in rows with proportional spacing. * **Responsive row sizing**: Use the [StyleHelper](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/stylehelper) to change row sizes at different viewport breakpoints. *** ## Properties Configure the following properties on the BlockLayout 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. * **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 layout. * `auto`: The intrinsic size of the element. * `fill`: Fills the remaining available space. When multiple elements 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. Elements without an explicit size fill the remaining space. A single value outside an array applies to all rows. * **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' ``` ### 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 ``` ### 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}%` ``` *** ## Examples ### Lay out content in rows Use BlockLayout to arrange content in multiple rows. This example shows the default behavior where rows share the available block space equally. ## Lay out content in rows ![A BlockLayout component arranging content in multiple rows.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-07/blocklayout-default-D7bOxHmZ.png) ## Lay out content in rows ##### React ```tsx import { reactExtension, BlockLayout, View, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ( 60 fill ); } ``` ##### JS ```js import {extension, BlockLayout, View} from '@shopify/ui-extensions/customer-account'; export default extension('customer-account.page.render', (root) => { const blockLayout = root.createComponent( BlockLayout, { rows: [60, 'fill'], }, [ root.createComponent(View, {border: 'base', padding: 'base'}, '60'), root.createComponent(View, {border: 'base', padding: 'base'}, 'fill'), ], ); root.appendChild(blockLayout); }); ``` *** ## Best practices * **Use explicit row sizes for unequal layouts**: Set the `rows` prop with specific sizes when rows should have different proportions. Default equal distribution works well for balanced layouts. * **Choose BlockLayout over BlockStack for row control**: Use BlockLayout when you need to define explicit row sizes. For uniform vertical spacing between elements, [BlockStack](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/blockstack) is simpler. * **Combine with StyleHelper for responsiveness**: Use [StyleHelper](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/stylehelper) to adjust row sizes at different viewport breakpoints. *** ## Limitations * BlockLayout fills the available block space by default. Children can't exceed the container height without setting overflow. * Row sizes are defined as a flat array. You can't assign sizes to specific rows by name. * BlockLayout doesn't support column-based layouts. Use [InlineLayout](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/inlinelayout) or [Grid](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/grid) for columns. ***