Skip to content
Developers

CSS, JavaScript and assets

You can add styles and scripts to a storefront in two ways:

  • Custom CSS and Custom JS: one stylesheet and one script, loaded on every page without touching a template. The quickest way to restyle a theme.
  • Theme assets: CSS and JavaScript files you create in the theme editor and load where you choose, with the asset_url filter.

Custom CSS and Custom JS

Section titled “Custom CSS and Custom JS”

  1. Open Content → Theme (/admin/themes), then Custom CSS (/admin/themes?p=custom_css) or Custom JS (/admin/themes?p=custom_js).

  2. Paste your code and click Save. Write plain CSS or JavaScript, without <style> or <script> tags.

The platform saves your code as a file and links it on every storefront page. The script is loaded with defer, so it runs once the page is parsed, after the theme’s own script: you can rely on the theme’s markup being there.

Custom JS
// Open the footer's external links in a new tab.
document.querySelectorAll('footer a[href^="http"]').forEach((link) => {
  if (link.host !== location.host) {
    link.target = '_blank';
    link.rel = 'noopener';
  }
});

Theme assets

Section titled “Theme assets”

  1. Open Content → Theme → Theme editor.

  2. Next to Assets, click Add a new asset, type a name and choose css or js. The editor creates an empty file and opens it.

  3. Write your code and click Save.

  4. Load the file from a template or a snippet, usually header.liquid or footer.liquid:

    {{ 'custom.css' | asset_url | stylesheet_tag }}
    {{ 'custom.js' | asset_url | script_tag }}

A theme asset is loaded only where you include it, so you can reserve a stylesheet for one template. The Assets list also shows the files of a theme installed from the library: open one and save it to replace the theme’s version with yours.

The theme editor creates CSS and JavaScript files only: it does not upload images or fonts. Use the image fields of the back office (logo, homepage sections, pages, theme options), which return image URLs your templates can print, or an absolute URL to a file you host. Fonts load best from a font provider, with an @import at the top of your CSS.

Versioned URLs

Section titled “Versioned URLs”

asset_url adds a version to the URL, taken from the moment the file last changed:

<link rel="stylesheet" href="/assets/…/custom.css?v=1760385600"/>

Saving the file changes the version, so returning visitors download the new file at once, while an unchanged file stays in their browser’s cache. Always load theme files through asset_url for that reason: a URL you write by hand gets no version, and a visitor may keep an old copy for a long time.

Two things are not versioned:

  • URLs inside your CSS (url(…) for a background image or a font). Change the file name, or add your own ?v=2, when you replace such a file.
  • The Custom CSS and Custom JS files. If a change does not show, reload the page without the cache before you look for a bug.

Load order

Section titled “Load order”

Stylesheets load in this order, each able to override the ones before it:

  1. The theme’s stylesheets.
  2. The stylesheets of the theme from the library, if any, then the colours set in its theme options.
  3. Styles some pages add for their own blocks.
  4. Custom CSS.
  5. Theme colours (Customize → General).
  6. Stylesheets your templates load with stylesheet_tag, where you print them.

Theme colours load after Custom CSS: to override a colour the admin set there, use a more specific selector. Scripts load in this order, all deferred: the theme’s script, the library theme’s scripts, then Custom JS.

The theme loads jQuery and, for Kindshare, Bootstrap 3 and Font Awesome 4: your code can use them without loading them again.