JavaScript and styles

Where assets live

Stylesheets and scripts belong in the theme's assets directory and are referenced through the asset_url filter, which serves them from the CDN with a cache-busting version.

└── theme
    ├── assets
    │   ├── main.css
    │   ├── _global.js
    │   ├── section.slideshow.css
    │   ├── block.product.css
    │   ...
    ...

The directory is flat, so mirror your sections/ and snippets/ names. A file called section.slideshow.css is obviously the stylesheet for sections/slideshow.liquid, and block.product.css for snippets/block.product.liquid.

Loading assets

Pair asset_url with the tag filter that matches how the asset should load:

Filter	Output
stylesheet_tag	A <link rel="stylesheet">.
script_tag	A blocking <script>.
script_tag_deferred	A <script defer>.
script_module	A <script type="module">.
script_module_deferred	A deferred <script type="module">.
preload_tag	A <link rel="preload">.

{{ 'main.css' | asset_url | stylesheet_tag }}
{{ '_global.js' | asset_url | script_tag_deferred }}

Default to script_tag_deferred. A blocking script_tag stops HTML parsing, and almost nothing in a theme needs to run before the document is built.

Keep asset loading close to what needs it

Load a section's stylesheet from the section file rather than the layout, so pages that don't use the section don't pay for it:

{{ 'section.slideshow.css' | asset_url | stylesheet_tag }}

<div class="slideshow">
  ...
</div>

Reserve the layout for what every page genuinely needs: the base stylesheet, fonts, and the shared scripts.

Inline styles and scripts

For the handful of values that depend on settings, the {% style %} tag keeps CSS in the section file. Use the section's wrapper as the scope, and pass settings through custom properties instead of writing whole rules in Liquid:

{% style %}
  #youcan-section--{{ section.id }} {
    --bg-color: {{ section.settings.bg_color.hex }};
    --top-spacing: {{ section.settings.top_spacing }}px;
  }
{% endstyle %}

Every section is rendered inside a wrapper element with an id of youcan-section-- plus the section's id, and the class youcan-section, so that selector always resolves, and two copies of the same section on one page stay independent.

The {% javascript %} tag does the same for scripts. Keep what goes in it small: wiring up an element, passing a setting to a component. Anything reusable belongs in assets where it can be cached.

Scope your CSS

Section stylesheets in assets are global once loaded. Scope them so a section can't restyle the rest of the page:

.youcan-section .slideshow__item { ... }

Prefer a single class per component over deep descendant chains, and drive variations with data attributes rather than generating separate rules per setting value:

<div class="slideshow" data-alignment="{{ section.settings.alignment }}">

.slideshow[data-alignment='center'] { text-align: center; }

Write less JavaScript

Native browser features cover most of what themes reach for: <details> for accordions, <dialog> for modals, CSS scroll snap for carousels, form validation attributes for inputs. Each one you use is code you don't ship, debug, or block rendering with.

When you do need JavaScript:

• Enhance server-rendered markup instead of building it on the client.
• Scope queries to the section, using its wrapper id, rather than document.querySelector across the page.
• Load heavy behaviour on interaction with a dynamic import() rather than at page load.
• Guard against the element not being there. Sections come and go while a seller is customizing.

const root = document.getElementById('youcan-section--{{ section.id }}');
if (root) {
  root.querySelector('[data-open]')?.addEventListener('click', open);
}

Third-party code

Every external stylesheet or script adds a DNS lookup, a connection, and a dependency you don't control. Self-host what you can by putting it in assets. For what you can't, load it deferred and warm the connection:

<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>