Stylesheet content subsetting

Shopify automatically subsets CSS from {% stylesheet %} tags so that each storefront page only loads the styles it needs. Instead of bundling all {% stylesheet %} CSS from every theme file into a single payload, Shopify identifies which files are part of the page's render tree — the set of Liquid files (sections, blocks, and snippets) that are actually rendered on that page — and includes only their CSS.

This reduces the amount of CSS that browsers download and parse, which improves page load times for merchants and their customers.

Anchor to How subsetting worksHow subsetting works

When a storefront page is rendered, Shopify determines which Liquid files are part of the page's render tree. Only the CSS from those files' {% stylesheet %} tags is included in the linked styles.css file.

For example, if sections/collection.liquid renders snippets/product-card.liquid using {% render 'product-card' %}, then both files' {% stylesheet %} CSS is included on any page that renders the collection section. The snippet's CSS is included because its parent (the collection section) is in the render tree.

Anchor to What isn't affectedWhat isn't affected

The following types of CSS aren't subject to subsetting:

• Asset stylesheets: CSS files in the assets/ folder that are loaded through {{ 'style.css' | asset_url | stylesheet_tag }} continue to work as before. They're included based on where you reference them in your layouts and templates.
• Inline styles: Inline style attributes on HTML elements aren't affected.
• HTML <style> tags: CSS in <style> tags (not {% stylesheet %}) renders as-is with the HTML output.
• CSS inside the liquid {% style %} tag: CSS inside the liquid {% style %} tag is not affected.

Anchor to Compatible and incompatible patternsCompatible and incompatible patterns

A theme is compatible with subsetting when each file's CSS classes are used only within that file or files it directly renders. Most themes that follow a co-located, component-scoped pattern for {% stylesheet %} tags are already compatible. The following examples show what works and what doesn't.

Anchor to Compatible pattern: self-contained stylesCompatible pattern: self-contained styles

CSS classes that are defined and used in the same file are always safe:

Anchor to Compatible pattern: parent styles used by rendered childrenCompatible pattern: parent styles used by rendered children

CSS classes that are defined in a parent file and used by a rendered child through {% render %} are safe, because the parent is always in the render tree when the child is:

Anchor to Incompatible pattern: cross-file CSS dependencyIncompatible pattern: cross-file CSS dependency

A CSS class that's defined in one file's {% stylesheet %} tag but used in a different, unrelated file is incompatible. If the defining file isn't in the page's render tree, then the styles won't be included:

In this example, footer.liquid uses .site-banner but doesn't define it. It relies on header.liquid's {% stylesheet %} being on the same page. If a page doesn't render the header section, then the class won't be available, and the footer won't be styled correctly.

Anchor to Checking your themeChecking your theme

The ValidScopedCSSClass check in Theme Check detects cross-file CSS dependencies. It's enabled by default in the recommended configuration.

Run Theme Check on your theme:

The check reports warnings when a CSS class that's used in an HTML class attribute is defined in another file's {% stylesheet %} tag, and that file isn't a direct ancestor in the render tree. For example:

CSS classes defined in assets/*.css are allowlisted, so they won't trigger warnings when used in Liquid files.

Anchor to Fixing flagged issuesFixing flagged issues

There are a few approaches to fixing any classes that have been flagged by the Theme Check linter:

Anchor to Move CSS to the file that uses itMove CSS to the file that uses it

If a class is used in one or a few specific files, then either add the class definition to each file's {% stylesheet %} tag, or define it once in a common parent.

Anchor to Move CSS to a shared asset stylesheetMove CSS to a shared asset stylesheet

If a class is truly global and used across many unrelated sections (such as utility classes or shared typography), then move it to a .css file in the assets/ folder and load it through stylesheet_tag in your layout:

Asset stylesheets aren't subject to subsetting and are always available on every page that loads them.

Anchor to Subsetting and the section rendering APISubsetting and the section rendering API

Subsetting also applies when sections are fetched dynamically. When you use the section rendering API to fetch a section, the response includes a <style data-section-stylesheet> tag containing the section's subsetted CSS:

If you insert the full section response into the DOM, then the styles are included automatically. If you insert only a portion of the response, then you also need to extract the <style data-section-stylesheet> element and insert it into the DOM so the section's styles are applied.