Assets

Assets are the static files in your theme. They include CSS, JavaScript, images, fonts, and any other files that do not change based on the page content. All assets are served through the CDN for fast loading.

The assets folder

Place your static files in the assets/ folder at the root of your theme:

assets/
  theme.css
  theme.js
  logo.png
  icons.svg
  custom-font.woff2

Loading assets in templates

Use the asset_url filter to get the CDN URL for any file in the assets folder:

<link rel="stylesheet" href="{{ 'theme.css' | asset_url }}">
<script src="{{ 'theme.js' | asset_url }}" defer></script>

For images:

<img src="{{ 'logo.png' | asset_url }}" alt="{{ store.name }}" />

The filter returns a full URL that points to the file on the CDN. You do not need to know the CDN path. The filter handles it for you.

Stylesheets

Your main stylesheet goes in the assets folder and is loaded in the layout file. Keep theme-wide styles here. Section-specific styles belong in {% stylesheet %} blocks inside each section.

<!-- In layout/theme.liquid -->
<link rel="stylesheet" href="{{ 'theme.css' | asset_url }}">

CSS custom properties

Use CSS custom properties for values that should be consistent across the theme. This makes it easy to change colours, fonts, and spacing in one place:

:root {
  --color-primary: #1a1a1a;
  --color-accent: #e63946;
  --color-background: #ffffff;
  --font-body: 'Inter', sans-serif;
  --font-heading: 'Playfair Display', serif;
  --page-width: 1200px;
  --spacing-section: 4rem;
}

Theme settings can override these values. In your layout, output the merchant's choices as inline CSS:

<style>
  :root {
    --color-primary: {{ theme.settings.primary_color }};
    --color-accent: {{ theme.settings.accent_color }};
    --font-body: {{ theme.settings.body_font.family }}, {{ theme.settings.body_font.fallback }};
  }
</style>

JavaScript

Load your main script with the defer attribute so it does not block page rendering:

<script src="{{ 'theme.js' | asset_url }}" defer></script>

Section-specific scripts belong in {% javascript %} blocks. The theme script handles global behaviour like cart drawers, mobile menus, and scroll effects.

Fonts

Upload custom font files to the assets folder and reference them in your CSS:

@font-face {
  font-family: 'CustomFont';
  src: url('custom-font.woff2') format('woff2');
  font-display: swap;
}

Use font-display: swap so text is visible while the font loads. This avoids a flash of invisible text.

If your theme uses the font_picker setting type, the selected font is loaded from the platform's font library and does not need a file in the assets folder.

SVG icons

A common pattern is to bundle all icons into a single SVG sprite sheet:

<!-- Load the sprite in the layout -->
{% render 'icon-sprite' %}

<!-- Use icons anywhere -->
<svg class="icon"><use href="#icon-cart"></use></svg>
<svg class="icon"><use href="#icon-search"></use></svg>

This keeps your HTML clean and lets you style icons with CSS.

Asset size and performance

Keep asset files as small as you can. Large files slow down the page and hurt the visitor's experience.

• Compress images before uploading them. Use WebP or AVIF where possible.
• Minify CSS and JavaScript for production.
• Use woff2 for fonts. It has the best compression.
• Load scripts with defer or async to avoid blocking the page.
• Use lazy loading for images below the fold.

The CDN handles caching and delivery. Your job is to keep the source files lean.