Skip to main content
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.

StyleHelper

The StyleHelper utility enables conditional property values based on viewport sizes and interactive states. Use StyleHelper to write responsive styles that adapt layout components to different screen sizes, hover states, and focus states in a concise and expressive way.

StyleHelper works with the following components to create responsive designs without custom CSS:

BlockLayoutInlineLayout
BlockSpacerInlineSpacer
BlockStackInlineStack
GridList
GridItemPressable
ImageScrollView
SkeletonImageView
Support
Targets (25)

Supported targets

Anchor to PropertiesProperties

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.

Anchor to ExamplesExamples

Anchor to Import the StyleHelperImport the StyleHelper

Import Style from the UI extensions package to use conditional style values. This example shows the basic import statement for both React and vanilla JS entry points.

Import the Style helper

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

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

function Extension() {
return (
<View
maxInlineSize={Style.default(200)
.when({viewportInlineSize: {min: 'small'}}, 300)
.when({viewportInlineSize: {min: 'medium'}}, 400)
.when({viewportInlineSize: {min: 'large'}}, 800)}
>
Responsive Content
</View>
);
}
import {Style, View, extension} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const view = root.createComponent(
View,
{
border: 'base',
padding: 'base',
maxInlineSize: Style.default(200)
.when({viewportInlineSize: {min: 'small'}}, 300)
.when({viewportInlineSize: {min: 'medium'}}, 400)
.when({viewportInlineSize: {min: 'large'}}, 800),
},
'Responsive Content',
);

root.appendChild(view);
});

Anchor to Create responsive grid columnsCreate responsive grid columns

Combine a default style with viewport-based conditions. In this example, the Grid's children stack by default and display side by side on viewports above the small breakpoint.

Create responsive grid columns

<Grid
columns={Style.default('fill').when({viewportInlineSize: {min: 'small'}}, [
'30%',
'70%',
])}
>
<View>Content</View>
<View>Content</View>
</Grid>
import {Style, Grid, View, extension} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const content1 = root.createComponent(View, {}, 'Content');
const content2 = root.createComponent(View, {}, 'Content');

const grid = root.createComponent(
Grid,
{
columns: Style.default('fill').when(
{viewportInlineSize: {min: 'small'}},
['30%', '70%'],
),
},
[content1, content2],
);

root.appendChild(grid);
});

Anchor to Apply hover stylesApply hover styles

Use a simple condition to change styling when a customer interacts with an element. In this example, the View's padding changes to loose on hover.

Apply hover styles

<Pressable
onPress={() => alert('press')}
border={Style.default(['base', 'dotted']).when(
{viewportInlineSize: {min: 'small'}},
['base', 'dotted', 'none', 'base'],
)}
>
Content
</Pressable>
import {Style, Pressable, extension} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const pressable = root.createComponent(
Pressable,
{
onPress: () => {},
border: Style.default(['base', 'dotted']).when(
{viewportInlineSize: {min: 'small'}},
['base', 'dotted', 'none', 'base'],
),
},
'Content',
);

root.appendChild(pressable);
});

Anchor to Conditionally hide contentConditionally hide content

Use the display property with conditional styles to hide content for certain viewport sizes. In this example, the View is hidden on small and larger screen sizes.

Conditionally hide content

<View
display={Style.default('auto').when(
{viewportInlineSize: {min: 'small'}},
'none',
)}
>
Content
</View>
import {Style, View, extension} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const view = root.createComponent(
View,
{
display: Style.default('auto').when(
{viewportInlineSize: {min: 'small'}},
'none',
),
},
'Content',
);

root.appendChild(view);
});

Anchor to Best practicesBest practices

  • Start with a default, then add conditions: Always define a base style using .default() before adding .when() conditions so there's a fallback for every scenario.
  • Keep conditions simple: Avoid chaining too many .when() calls. If a style requires more than two or three conditions, consider simplifying the design.
  • Use viewport conditions for layout shifts: Reserve viewportInlineSize conditions for meaningful layout changes like column count, not minor spacing tweaks.

Anchor to LimitationsLimitations

  • StyleHelper supports only hover, focus, and viewportInlineSize conditions. Other CSS pseudo-classes and media features aren't available.
  • The viewport breakpoints are limited to small, medium, and large. Custom breakpoint values aren't supported.
  • StyleHelper can only be used with component properties that accept conditional style values. Not all properties support it.
Was this page helpful?