Skip to content
Tutorials Center
My learning

Topics

Lesson 61 of 61 ยท Practice and Review

Shopify Theme Cheat Sheet

A one-page Shopify theme cheat sheet: Liquid tags and filters, schema setting types, Ajax cart endpoints, Shopify CLI commands and the theme file structure.

This is the page to keep open while you build a theme. It teaches nothing new: every line is a fact from an earlier lesson, shortened until you can scan it. When something here is unclear, follow the link to the lesson that explains it.

The sheet follows the order in which you usually reach for things: the file structure, Liquid tags, Liquid filters, schema setting types, the Ajax endpoints and finally the Shopify CLI. Two runnable stand-ins sit in the middle. They are small JavaScript programs, not Shopify's code: Shopify's Liquid engine and servers only exist on Shopify, so all the real theme code on this page is read-only.

Names and flags below target current Online Store 2.0 themes and the Shopify CLI 3.x line. Shopify retires and adds features over time, so check the Liquid reference and shopify theme --help before you rely on a rarely used item.

File structure

A theme is a folder with these top-level directories. Shopify only reads code from them. See The Theme File Structure for details.

Folder What goes there
layout/ Page shells such as theme.liquid and password.liquid.
templates/ One file per page type, usually JSON that lists sections. Customer templates live in templates/customers/.
sections/ Configurable page parts with a {% schema %} tag.
blocks/ Theme blocks that sections can reuse.
snippets/ Reusable fragments you call with render.
assets/ CSS, JavaScript, images and fonts.
config/ settings_schema.json and settings_data.json.
locales/ Translation files such as en.default.json.
TEXT
my-theme/
  assets/      base.css, theme.js
  blocks/      text.liquid
  config/      settings_schema.json, settings_data.json
  layout/      theme.liquid
  locales/     en.default.json, fr.json
  sections/    header.liquid, main-product.liquid
  snippets/    product-card.liquid
  templates/   index.json, product.json, customers/login.json

Liquid tags

Output uses {{ ... }}. Logic uses {% ... %}. Add a dash on either side ({{-, -%}) to trim whitespace. Lessons: Liquid Basics, Conditions, Loops, Variables.

Group Tags
Conditions if, elsif, else, unless, case / when
Loops for (with limit, offset, reversed, else), break, continue, cycle, tablerow, paginate
Variables assign, capture, increment, decrement
Reuse render (isolated scope), section, sections (section groups), content_for
Output helpers echo, liquid (a block of tags without delimiters), form
Assets in a file {% stylesheet %}, {% javascript %}, {% style %}
Documentation {% comment %}, {% doc %}, {% raw %}
Section files only {% schema %}
Legacy include (use render instead)

Some patterns you will type again and again:

LIQUID
{%- if product.available -%}
  {{ product.price | money }}
{%- else -%}
  {{ 'products.product.sold_out' | t }}
{%- endif -%}

{% for product in collection.products limit: 4 %}
  {% render 'product-card', product: product, show_vendor: true %}
{% else %}
  <p>{{ 'sections.collection.empty' | t }}</p>
{% endfor %}

{% content_for 'blocks' %}

The forloop object gives you index, index0, first, last and length. Falsy values in Liquid are only false and nil, so 0 and the empty string are truthy. Test emptiness with == blank or == empty. See Liquid Pitfalls.

Liquid filters

Filters chain from left to right: {{ title | strip | truncate: 40 | upcase }}. The standard ones are explained in Filters: Strings, Math, Arrays, the Shopify ones in Shopify Filters.

Kind Filters
Strings append, prepend, upcase, downcase, capitalize, strip, truncate, truncatewords, replace, remove, split, strip_html, newline_to_br, escape, url_encode, handleize (alias handle)
Math plus, minus, times, divided_by, modulo, round, ceil, floor, abs, at_least, at_most
Arrays join, first, last, size, map, where, sort, sort_natural, reverse, uniq, concat, compact, sum
Defaults default (replaces nil, false and empty values)
Money money, money_with_currency, money_without_currency, money_without_trailing_zeros
Media image_url, image_tag, placeholder_svg_tag, video_tag, external_video_tag
Files asset_url, file_url, stylesheet_tag
Language and data t (translate), date, json, pluralize

Two reminders. Prices are integers in the smallest currency unit, so always use a money filter. And divided_by with an integer divisor does integer division, so {{ 7 | divided_by: 2 }} is 3 while {{ 7 | divided_by: 2.0 }} is 3.5.

The first stand-in below is a tiny filter pipeline. It is not Shopify's engine, but it applies filters the same way: left to right, each result feeding the next.

JS A filter pipeline in 30 lines (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Schema setting types

Settings are declared in a section's {% schema %} tag, in blocks/ files, and in config/settings_schema.json. Each setting needs id, type and label. Lessons: Schema Settings in Depth, Building a Section.

Category Types
Text text, textarea, richtext, inline_richtext, html, liquid
Numbers and choices number, range, checkbox, radio, select, text_alignment
Color color, color_background, color_scheme, color_scheme_group
Media image_picker, video, video_url
Links and pages url, link_list, page, blog, article
Resources product, product_list, collection, collection_list, metaobject, metaobject_list
Typography font_picker
Layout of the form header, paragraph (display only, no value)

A minimal section schema, read-only:

LIQUID
{% schema %}
{
  "name": "Promo banner",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Summer sale" },
    { "type": "range", "id": "padding", "label": "Padding", "min": 0, "max": 80, "step": 4, "unit": "px", "default": 32 },
    { "type": "select", "id": "align", "label": "Alignment", "default": "center",
      "options": [
        { "value": "start", "label": "Left" },
        { "value": "center", "label": "Center" }
      ] }
  ],
  "blocks": [{ "type": "@app" }, { "type": "text" }],
  "presets": [{ "name": "Promo banner" }]
}
{% endschema %}

Useful extras: visible_if shows a setting only when a condition holds, max_blocks limits blocks, presets makes a section appear in the "Add section" list, and info adds help text under a setting. Inside the section you read values with section.settings.heading and block.settings.<id>; always print {{ block.shopify_attributes }} on the block's outer element so the theme editor can select it.

Ajax cart and storefront endpoints

All of these are relative to the store's domain. Use the routes object (routes.cart_add_url, routes.cart_url and friends) instead of hard-coding paths, so Markets with a language prefix keep working. Lessons: The Ajax Cart API, Predictive Search, The Section Rendering API.

Endpoint Method Purpose
/cart.js GET Return the cart as JSON.
/cart/add.js POST Add one or more items (id, quantity, properties, selling_plan).
/cart/update.js POST Set quantities for many lines, or update the note and attributes.
/cart/change.js POST Change one line by line (1-based) or id.
/cart/clear.js POST Remove every line.
/cart/shipping_rates.json GET Estimate shipping for an address.
/products/<handle>.js GET Product JSON with variants.
/search/suggest.json GET Predictive search; pass q and resources[type].
/recommendations/products.json GET Product recommendations for a product_id.
any page URL with ?sections=a,b or ?section_id=a GET Return rendered HTML for named sections as JSON or text.

A change request sends quantity: 0 to remove a line. Errors come back with HTTP status 422 and a description message, for example when stock runs out. The cart endpoints are rate limited, so do not call them on every keystroke.

JavaScript
// Read-only: real storefront code, runs only on a Shopify store.
const response = await fetch(window.Shopify.routes.root + 'cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    items: [{ id: 44001122, quantity: 2, properties: { Engraving: 'A.K.' } }],
    sections: 'cart-drawer,cart-icon-bubble',
  }),
});
const result = await response.json();

The second stand-in builds the same kinds of request objects without sending them, so you can see exactly what each endpoint expects. The "server" is fake: nothing leaves the page.

flowchart TD
  A["Cart action"] --> B{"What changes?"}
  B -->|"Add item"| C["POST /cart/add.js"]
  B -->|"One line quantity"| D["POST /cart/change.js"]
  B -->|"Many lines or note"| E["POST /cart/update.js"]
  B -->|"Empty the cart"| F["POST /cart/clear.js"]
  C --> G["Ask for sections in the same call"]
  D --> G
  E --> G
  G --> H["Replace the returned HTML"]

Picking the right cart endpoint, then refreshing the page parts from the same response.

JS Cart request builder (stand-in, nothing is sent)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Shopify CLI commands

Install the CLI with your package manager (it needs a current Node.js LTS), then run theme commands from inside the theme folder. See Setting Up and Version Control.

Command What it does
shopify theme init Create a new theme from a starter.
shopify theme dev --store my-store.myshopify.com Serve a local preview with hot reload against a development theme.
shopify theme pull Download the remote theme into the current folder.
shopify theme push Upload local files; use --unpublished to create a new theme, --theme to target one.
shopify theme check Run Theme Check on your code.
shopify theme list List the store's themes with IDs and roles.
shopify theme publish Make a theme live (asks for confirmation).
shopify theme share Create a shareable preview link.
shopify theme open Open the preview or the editor.
shopify theme console Evaluate Liquid against a store interactively.
shopify theme profile Profile Liquid rendering of a page.
shopify theme package Zip the theme for upload.
shopify theme delete Delete a theme.

Flags worth remembering: --only and --ignore limit which files move, --nodelete keeps remote files that do not exist locally, --live targets the published theme, and --allow-live is required for pushing to it without a prompt. Put things you never want to upload in .shopifyignore.

Terminal
# Read-only: needs a Shopify store and an authenticated CLI.
shopify theme dev --store my-store.myshopify.com
shopify theme check
shopify theme push --unpublished --theme "Spring redesign"

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which values are falsy in Liquid?

    Liquid treats only false and nil as falsy. Zero and the empty string are truthy, so compare with blank or empty when you need to detect emptiness.
  2. 2. You want to change the quantity of a single cart line, or remove it. Which endpoint fits best?

    /cart/change.js targets one line by its 1-based position or by id. Sending quantity 0 removes the line.
  3. 3. Which setting type shows a heading in the theme editor form without storing any value?

    header (like paragraph) is a display-only entry that organizes the settings form. It has no id and stores no value.
  4. 4. Which command uploads your local files as a brand-new unpublished theme?

    push uploads local files, and the --unpublished flag creates a new theme instead of overwriting an existing one.

Summary

  • A theme has eight folders: layout, templates, sections, blocks, snippets, assets, config and locales.
  • Liquid has output ({{ }}) and logic ({% %}); only false and nil are falsy, and render replaces include.
  • Filters chain left to right; use money filters for prices and image_url / asset_url for files.
  • Schema settings have an id, type and label; header and paragraph only organize the form.
  • Cart changes go through /cart/add.js, /cart/change.js, /cart/update.js and /cart/clear.js, and the sections parameter returns fresh HTML in the same response.
  • The CLI commands you use daily are theme dev, pull, push and check.

That completes the Shopify theme course. Back to the start: What Is a Shopify Theme?