• Standard attributes
  • Style panel settings
  • Size
  • Spacing
  • Layout
  • Usage

Style settings

Developer preview

Style settings are currently only available as part of the Flex sections developer preview.

Style settings are a new category of input settings that can hold values that map to CSS properties. Style settings can hold values for different breakpoints, unlike other input settings which share the same value across breakpoints.

There are two categories of Style settings:

Category Description
Style panel settings Shopify-organized settings that map to categories of CSS properties, such as layout, size, and spacing.
Style input settings
(coming soon) 		Input settings that can hold a value adaptable by breakpoint tied to the CSS property it can control.

To learn how to access the values of these settings for use in your theme, refer to usage.

Standard attributes

Anchor link to section titled "Standard attributes"

The following are standard attributes across all style settings:

Attribute Description Required
type The setting type, which can be any of the style panel setting types or input setting types (coming soon). Yes
id The setting ID, which is used to access the setting value. Yes
label The setting label, which will show in the theme editor. Yes
default The default value(s) for the setting. No
info An option for informational text about the setting. No

Style panel settings

Anchor link to section titled "Style panel settings"

Style panel settings combine multiple inputs into a single panel, simplifying the setup of merchant-editable style settings in your theme. By adding a single style panel setting, you get a full set of related style settings that map to CSS properties. Style panel settings are evergreen, which means that additional CSS properties will be added to them over time.

The available types of panel settings are:

  • Size
  • Spacing
  • Layout

More types of panel settings will be introduced in the future.

Size

Anchor link to section titled "Size"

The style setting panel of type style.size_panel outputs settings to control the width and height of an element.

For example, the following setting generates the following output:

The following properties and corresponding values are supported:

Properties Supported values Default
width, min-width auto, %, px auto
height, min-height auto, %, px auto
max-width, max-height %, px, none none
flex-grow number 0
flex-shrink number 1
flex-basis auto, %, px auto

Spacing

Anchor link to section titled "Spacing"

The style setting panel of type style.spacing_panel outputs settings to control the padding and margin of an element.

For example, the following setting generates the following output:

The following properties and corresponding values are supported:

Properties Supported values Default
padding
  • padding-left
  • padding-right
  • padding-top
  • padding-bottom
padding-block
  • padding-block-start
  • padding-block-end
padding-inline
  • padding-inline-start
  • padding-inline-end
 %, px 0px
margin
  • margin-left
  • margin-right
  • margin-top
  • margin-bottom
margin-block
  • margin-block-start
  • margin-block-end
margin-inline
  • margin-inline-start
  • margin-inline-end
 %, px 0px

Note

The style.spacing_panel setting supports shorthand and longhand properties as input for margin and padding. It also supports a combination of longhand and shorthand properties, in which case declarations are merged in the order they are encountered and the theme editor will show the resulting computed values for the longhand properties.

Physical properties are supported as input, but the storefront output will always be mapped to the corresponding logical properties.

Layout

Anchor link to section titled "Layout"

The style setting panel of type style.layout_panel outputs settings to control the direction, positioning, and alignment of items inside a container.

For example, the following setting generates the following output:

The following properties and corresponding values are supported:

Properties Supported values Default
display flex flex
flex-direction row, column row
flex-wrap wrap, no-wrap no-wrap
align-items flex-start, center, flex-end, baseline, stretch flex-start
justify-content flex-start, center, flex-end, space-around, space-between, space-evenly flex-start
align-content flex-start, center, flex-end, space-around, space-between, space-evenly, baseline, normal normal
gap
  • column-gap
  • row-gap
 %, px 0px

Usage

Anchor link to section titled "Usage"

When working with style settings, you should familiarize yourself with the following:

  • Using style settings
  • Accessing style settings
  • Applying style settings on elements
  • Providing breakpoint-specific values for style settings
  • Overriding default style setting values

Using style settings

Anchor link to section titled "Using style settings"

You can currently use style settings in the following places:

  • Sections
  • Theme blocks
  • Theme settings
  • Section-defined blocks

And you'll also soon be able to use them in:

  • App blocks

Accessing style settings

Anchor link to section titled "Accessing style settings"

Like other input settings, style settings can be accessed in Liquid using the id attribute of their associated setting. For example, given a setting with an id of "layout":

Applying style settings on elements

Anchor link to section titled "Applying style settings on elements"

Style settings can be applied on any given element using the class_list filter in Liquid:

This will apply all of the default values for this style setting to this element, and any merchant edits made in the theme editor.

You can apply style settings on multiple different elements, or apply multiple different style settings to the same element. For example:

If you want to apply all the style settings in a section or block on the same element, you can use the class_list filter directly on block.settings or section.settings:

Caution

You can apply multiple style panel settings of different types on the same element, but applying multiple style panel settings of the same type on the same element will result in them overriding one another.

Applying style settings on the appropriate element

Anchor link to section titled "Applying style settings on the appropriate element"

You can use style settings as many times as you wish, and apply them on any element. However, it’s important to note that where you apply style settings can have an impact.

For example, here are some recommendations on where to apply style settings:

  • We recommend applying the style.layout_panel setting on the element that wraps the {% content_for "blocks" %} tag in situations where you want to provide merchants with complete layout flexibility.
  • We recommend that the style.size_panel setting be applied on the outermost element if you plan on using it to allow merchants to control the size of blocks. This requirement is due to the fact that some properties, like flex-grow, flex-shrink and flex-basis only have an effect if they are applied on the direct descendants of the flexbox container element, which will typically be the wrapper of the {% content_for "blocks" %} tag.

With these recommendations in mind, here is an example of applying the style.size_panel setting on the outermost element of a theme block:

Note

Shopify automatically wraps the contents of theme blocks in a wrapper element. To opt-out of this behavior, you can set the tag attribute to null. When the tag attribute is set to null, Shopify will no longer wrap the contents of the block in a wrapper element, and instead directly output the contents of the block.

It’s important that the block be tagged with {{ block.shopify_attributes }} for it to be detected by the theme editor. For additional details, refer to Rendering blocks without a wrapper.

Providing breakpoint-specific values for style settings

Anchor link to section titled "Providing breakpoint-specific values for style settings"

Style settings support storing values for different breakpoints. You can specify values specific to each breakpoint in the default settings and presets.

To author breakpoint-specific values for styles, you can override a specific style property for a given breakpoint using @media queries

For example, here is how you can update the default value for the padding and margin properties in a style.spacing_panel setting:

In the theme editor, these values will appear as overrides in the sidebar when a merchant switches over to the mobile breakpoint.

Note

Currently, only the mobile breakpoint is available, but you can expect more breakpoints to be introduced in the future, such as a tablet breakpoint. The default value for the mobile breakpoint is set to 750 pixels and below. In a future release, themes will be able to configure this value and the value of other breakpoints introduced in the future.

Overriding default style setting values

Anchor link to section titled "Overriding default style setting values"

You can override default values for style settings in presets. Merchant overrides will be stored in JSON templates.

Here is an example of providing a Columns preset that flows horizontally and a Rows preset that flows vertically:

As you can see, only the flex-direction property needs to be overridden, while other properties will remain set to their default values.

Merchant overrides made in the theme editor will be stored in the corresponding template file that the merchant is editing:

On this page

  • Standard attributes
  • Style panel settings
  • Size
  • Spacing
  • Layout
  • Usage