--- title: BlockSpacer description: >- The BlockSpacer component creates empty vertical space between elements. Use BlockSpacer to insert variable amounts of block-axis spacing when elements need different gaps, such as adding extra breathing room between major content groups. 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/blockspacer md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/blockspacer.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. # BlockSpacer The BlockSpacer component creates empty vertical space between elements. Use BlockSpacer to insert variable amounts of block-axis spacing when elements need different gaps, such as adding extra breathing room between major content groups. BlockSpacer supports predefined spacing values from the design token set for consistent vertical rhythm. When all elements need the same gap, use [BlockStack](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/blockstack) with a `spacing` prop instead. ### 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 * **Variable vertical spacing**: Insert different amounts of space between elements when a uniform gap doesn't fit the design. * **Section breaks**: Add extra space between major content groups without using a visual divider. * **Conditional spacing**: Use with [StyleHelper](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/stylehelper) to adjust spacing at different viewport sizes. * **Visual breathing room**: Create whitespace between dense content areas to improve readability and scannability. *** ## Properties Configure the following properties on the BlockSpacer component. * **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. * **spacing** **MaybeResponsiveConditionalStyle\** **Default: 'base'** The size of the spacer. ### 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 ``` ### 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 ``` ### 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; } ``` ### 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' ``` ### Style​Helper The [StyleHelper](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/stylehelper) utility lets you write conditional values for the `spacing` property based on viewport size or interaction state. Use it to adjust BlockSpacer spacing responsively, such as applying tighter spacing on small screens and looser spacing on larger viewports. Configure the following style properties. * **default** **\(defaultValue: T) => StylesConditionalStyle\** **required** Sets an optional default value to use when no other condition is met. * **when** **\(conditions: StylesConditions, value: T) => StylesConditionalStyle\** **required** Adjusts the style based on different conditions. All conditions, expressed as a literal object, must be met for the associated value to be applied. The `when` method can be chained together to build more complex styles. ### StylesConditionalStyle * conditionals An array of conditional values. ```ts StylesConditionalValue[] ``` * default The default value applied when none of the conditional values specified in \`conditionals\` are met. ```ts T ``` ### StylesConditionalValue * 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 ``` ### StylesBaseConditions The full set of conditions available for conditional styling. At least one condition must be specified. * focus Applies when the component has keyboard or programmatic focus. ```ts true ``` * hover Applies when the user is hovering over the component with a pointer device. ```ts true ``` * resolution A minimum device pixel ratio that must be met. Higher values target high-density (Retina) displays. ```ts 1 | 1.3 | 1.5 | 2 | 2.6 | 3 | 3.5 | 4 ``` * viewportInlineSize A minimum viewport inline-size breakpoint that must be met. ```ts { min: ViewportInlineSize; } ``` ### ViewportInlineSize A keyword that maps to a viewport inline-size breakpoint from the design system. - \`extraSmall\`: A very narrow viewport, typically small phones. - \`small\`: A narrow viewport, such as a large phone or small tablet. - \`medium\`: A medium viewport, such as a tablet in landscape. - \`large\`: A wide viewport, such as a desktop display. ```ts 'extraSmall' | 'small' | 'medium' | 'large' ``` ### StylesConditions The set of conditions available for viewport-responsive and interactive styling. At least one condition must be specified. * focus Applies when the component has keyboard or programmatic focus. ```ts true ``` * hover Applies when the user is hovering over the component with a pointer device. ```ts true ``` * viewportInlineSize A minimum viewport inline-size breakpoint that must be met. ```ts { min: ViewportInlineSize; } ``` *** ## Examples ### Add variable vertical spacing Use BlockSpacer to insert specific amounts of vertical space between elements. This is useful when you need different spacing values in the same layout. ## Add variable vertical spacing ![A BlockSpacer creating vertical space between elements.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-07/blockspacer-default-ycbBn7A0.png) ## Add variable vertical spacing ##### React ```tsx import { reactExtension, BlockSpacer, View, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ( <> View View ); } ``` ##### JS ```js import {extension, BlockSpacer, View} from '@shopify/ui-extensions/customer-account'; export default extension('customer-account.page.render', (root) => { const blockSpacer = root.createComponent(View, undefined, [ root.createComponent(View, {border: 'base', padding: 'base'}, 'View'), root.createComponent(BlockSpacer, {spacing: 'loose'}), root.createComponent(View, {border: 'base', padding: 'base'}, 'View'), ]); root.appendChild(blockSpacer); }); ``` *** ## Best practices * **Set `spacing` explicitly**: BlockSpacer defaults to `base`. Always set the `spacing` prop to make the intended gap size clear and avoid relying on the default. * **Use StyleHelper for responsive spacing**: Wrap the `spacing` value with `Style.default().when()` to apply tighter spacing on small viewports and looser spacing on larger ones. * **Don't stack multiple spacers**: Use a single BlockSpacer with a larger `spacing` value like `loose` or `extraLoose` instead of placing multiple spacers in a row. *** ## Limitations * BlockSpacer only creates vertical (block-axis) space. For horizontal spacing, use [InlineSpacer](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/inlinespacer). * BlockSpacer is an empty element. It can't contain children or display content. * Spacing values are limited to the predefined design token set. Custom pixel values aren't supported. ***