Migrate to Polaris

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.

Choose a version:

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 with a spacing prop instead.

Support

Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the BlockSpacer component.

Anchor to id 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.
Anchor to spacing spacing <> 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.

T | ConditionalStyle<T, ViewportSizeCondition>

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
```

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; }
```

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 StyleHelperStyleHelper

The 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.

Anchor to default default <T>(defaultValue: T) => <T, > required: Sets an optional default value to use when no other condition is met.
Anchor to when when <T>(conditions: , value: T) => <T, > 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.

StylesConditionalValue<T, AcceptedConditions>[]

default
The default value applied when none of the conditional values specified in `conditionals` are met.
```
T
```

StylesConditionalValue

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
```

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.
```
true
```
hover
Applies when the user is hovering over the component with a pointer device.
```
true
```
resolution
A minimum device pixel ratio that must be met. Higher values target high-density (Retina) displays.
```
1 | 1.3 | 1.5 | 2 | 2.6 | 3 | 3.5 | 4
```
viewportInlineSize
A minimum viewport inline-size breakpoint that must be met.
```
{ 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.

'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.
```
true
```
hover
Applies when the user is hovering over the component with a pointer device.
```
true
```
viewportInlineSize
A minimum viewport inline-size breakpoint that must be met.
```
{ min: ViewportInlineSize; }
```

Anchor to ExamplesExamples

Anchor to Add variable vertical spacingAdd 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.

Add variable vertical spacing

import {

reactExtension,

BlockSpacer,

View,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

View

</View>

View

</View>

</>

);

}

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);

});

React

import {
  reactExtension,
  BlockSpacer,
  View,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <>
      <View border="base" padding="base">
        View
      </View>
      <BlockSpacer spacing="loose" />
      <View border="base" padding="base">
        View
      </View>
    </>
  );
}

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);
});

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

BlockSpacer only creates vertical (block-axis) space. For horizontal spacing, use 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.

Was this page helpful?