Shopify Themes

https://shopify.dev/docs/storefronts/themes/
Admin
Shopify Themes allows developers to build fast, flexible, and customizable themes for Shopify...
Tokens:498,822
Snippets:4,149
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example output for video_url setting

Source: https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings

Example output for the video_url setting when using the YouTube video with ID _9VUPq3SxOc.

```text
ID: _9VUPq3SxOc
Type: youtube
```

--------------------------------

### Complete example with source, merge, and diffs

Source: https://shopify.dev/docs/storefronts/themes/tools/cli/theme-preview-overrides

Complete example combining per-file operations: source, merge, and per-file diffs in a single theme_changes object.

```json
{
  "metadata": {
    "version": "0.1.0"
  },
  "theme_changes": {
    "templates/index.json": {
      "merge": {
        "current": {
          "product_image_size": "large"
        }
      }
    },
    "templates/product.liquid": {
      "source": "<div>{{ product.title }}</div>"
    },
    "templates/price.liquid": {
      "diffs": "3a4,6\n {% render 'sale-badge' %}\n"
    }
  }
}
```

--------------------------------

### Install Shopify AI Toolkit for Hermes

Source: https://shopify.dev/docs/storefronts/themes/getting-started/create

Download and run the install script for Hermes. The script is fetched from the Shopify-AI-Toolkit repository and executed locally.

```terminal
curl -fsSL https://raw.githubusercontent.com/Shopify/Shopify-AI-Toolkit/main/.hermes-plugin/install.sh -o /tmp/shopify-hermes-install.sh
bash /tmp/shopify-hermes-install.sh
```

--------------------------------

### theme_info object example

Source: https://shopify.dev/docs/storefronts/themes/architecture/config/settings-schema-json

Example of adding theme_info metadata to settings_schema.json. All attributes are required, but only one of theme_support_email or theme_support_url is needed; including both or omitting any other attribute results in an error.

```json
[
  {
    "name": "theme_info",
    "theme_name": "Dawn",
    "theme_author": "Shopify",
    "theme_version": "1.0.0",
    "theme_documentation_url": "https:\/\/help.shopify.com\/manual\/online-store\/themes\/os20\/themes-by-shopify\/dawn",
    "theme_support_url": "https:\/\/support.shopify.com\/",
  },
  ...
]
```

--------------------------------

### Document snippet usage with @example in Liquid

Source: https://shopify.dev/docs/storefronts/themes/tools/liquid-doc.md

Demonstrates the @example tag for documenting usage of a snippet. Multiple examples are supported, and multi-line examples are automatically formatted to start on a new line.

```liquid
{% doc %}
  Price display snippet


  @param {number} price - Price value
  @param {boolean} [show_compare_at] - Whether to show compare-at price


  @example
  {% render 'price', price: product.price, show_compare_at: true %}


  @example
  {% render 'price',
    price: variant.price,
    show_compare_at: false
  %}
{% enddoc %}
```

--------------------------------

### Install Theme Check via Shopify CLI

Source: https://shopify.dev/docs/storefronts/themes/best-practices/performance/theme-check-tool

Install Shopify CLI globally with npm, then verify the installation with the version command. This is the prerequisite for using Theme Check.

```bash
npm install -g @shopify/cli
shopify version
```

--------------------------------

### Install Shopify AI Toolkit for Pi

Source: https://shopify.dev/docs/storefronts/themes/getting-started/create

Run this command in your terminal to install the package from npm for Pi.

```terminal
pi install npm:@shopify/ai-toolkit
```

--------------------------------

### Example search URL with query parameters

Source: https://shopify.dev/docs/storefronts/themes/navigation-search/search

Example URL structure for a Shopify search with the query parameters `q`, `type`, `options[unavailable_products]`, and `options[prefix]`.

```text
/search?q=snow&type=product,page&options[unavailable_products]=hide&options[prefix]=last
```

--------------------------------

### Example alternate template file name

Source: https://shopify.dev/docs/storefronts/themes/architecture/templates/alternate-templates

Example file name for an alternate JSON product template with the name 'alternate'.

```text
product.alternate.json
```

--------------------------------

### Install with Yarn

Source: https://shopify.dev/docs/storefronts/themes/tools/liquid-prettier-plugin

Install the Shopify Liquid Prettier Plugin and Prettier as dev dependencies using Yarn.

```terminal
yarn add --dev prettier @shopify/prettier-plugin-liquid
```

--------------------------------

### Install with npm

Source: https://shopify.dev/docs/storefronts/themes/tools/liquid-prettier-plugin

Install the Shopify Liquid Prettier Plugin and Prettier as dev dependencies using npm.

```terminal
npm install --save-dev prettier @shopify/prettier-plugin-liquid
```

--------------------------------

### Basic setting example with visible_if

Source: https://shopify.dev/docs/storefronts/themes/architecture/settings

Basic example of a settings schema with a header, text input, and two select dropdowns. The second select uses visible_if to conditionally show based on the layout_style setting.

```json
{
  ...
  "settings": [
    {
      "type": "header",
      "content": "My settings"
    },
    {
      "type": "text",
      "id": "my_id",
      "label": "My setting label",
      "default": "Enter text here"
    },
    {
      "type": "select",
      "id": "layout_style",
      "label": "type",
      "options": [
        {
          "value": "flex",
          "label": "Stack"
        },
        {
          "value": "grid",
          "label": "Grid"
        }
      ],
      "default": "flex"
    },
    {
      "type": "select",
      "id": "content_direction",
      "label": "Direction",
      "options": [
        { "value": "row", "label": "Horizontal" },
        { "value": "column", "label": "Vertical" }
      ],
      "default": "column",
      "visible_if": "{{ block.settings.layout_style == 'flex' }}"
    }
  ],
  ...
}
```

--------------------------------

### GitHub Actions workflow to deploy theme with Shopify CLI

Source: https://shopify.dev/docs/storefronts/themes/tools/cli/ci-cd

Example GitHub Actions workflow that pushes a theme to a Shopify store when code is pushed to the main branch. It sets up Node.js, installs Shopify CLI globally, and runs the theme push command with the required environment variables.

```yaml
name: Theme deploy


on: [push]


jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20


      - name: Install Shopify CLI
        run: npm install -g @shopify/cli


      - name: Upload theme
        run: |
          shopify theme push \
            --json \
            --theme your-theme-name-or-id \
            --store ${{ secrets.SHOPIFY_FLAG_STORE }} \
            --password ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}

```

--------------------------------

### Install Shopify AI Toolkit for OpenClaw

Source: https://shopify.dev/docs/storefronts/themes/getting-started/create

Run this command in your terminal to install the Shopify plugin from npm for OpenClaw.

```terminal
openclaw plugins install npm:@shopify/ai-toolkit
```

--------------------------------

### Install Shopify AI Toolkit for Antigravity CLI

Source: https://shopify.dev/docs/storefronts/themes/getting-started/create

Run this command in your terminal to install the Shopify plugin for Antigravity CLI.

```terminal
agy plugin install https://github.com/Shopify/shopify-ai-toolkit
```

--------------------------------

### Output of shopify theme info

Source: https://shopify.dev/docs/storefronts/themes/tools/cli

Example output showing the theme configuration, including the store name and other details.

```terminal
THEME CONFIGURATION
-----------------------
Store   my-store.myshopify.com
...
```

--------------------------------

### Install Shopify AI Toolkit Plugin from Source in VS Code

Source: https://shopify.dev/docs/storefronts/themes/getting-started/create

Use the VS Code Command Palette to install the plugin from source. When prompted, enter the repository URL: https://github.com/Shopify/shopify-ai-toolkit.

```plaintext
Chat: Install Plugin From Source
```

```plaintext
https://github.com/Shopify/shopify-ai-toolkit
```

--------------------------------

### Product thumbnails with media preview_image

Source: https://shopify.dev/docs/storefronts/themes/product-merchandising/media/support-media

Use the `preview_image` attribute of the media object to display a thumbnail for each media source on the product page. The example adds a `data-thumbnail-id` attribute intended to be used with the `data-media-id` attribute from the general media loop example to associate thumbnails with their media displays.

```liquid
{% if product.media.size > 1 %}
  <div className="thumbnails-wrapper">
    {% for media in product.media %}
      <a data-thumbnail-id="{{ media.id }}">
        {{ media.preview_image | image_url: width: 110, height: 110, scale: 2 | image_tag: media.alt, 'product-single__thumbnail-image' }}
      </a>
    {% endfor %}
  </div>
{% endif %}
```

--------------------------------

### Liquid snippet documentation with @param and @example

Source: https://shopify.dev/docs/storefronts/themes/tools/liquid-doc.md

Shows the full structure of a Liquid doc comment for a snippet, including a description, @param annotations, and an @example render tag. Use this as a template when documenting snippets or blocks.

```liquid
{% doc %}
  Provides an example of a snippet description.


  @param {string} title - The title to display
  @param {number} [max_items] - Optional maximum number of items to show


  @example
  {% render 'example-snippet', title: 'Featured Products', max_items: 3 %}
{% enddoc %}
```

--------------------------------

### Theme zip structure example

Source: https://shopify.dev/docs/storefronts/themes/store/success/updates

Example theme zip structure showing required top-level folders and preset listing folders under /listings. Each preset folder uses kebab-case names and contains a /templates folder that overrides the base set; /sections is optional and only included when preset-specific changes exist. Root /templates and /sections hold the complete base set of .json files.

```json
/assets
/blocks
/config
/layout
/locales
/listings
	/embiggen
		/templates
			404.json
			index.json
			product.json
	/canine-gourmand
		/templates
			index.json
			blog.json
			collection.json
			cart.json
		/sections
			header-group.json
	/zenful
		/templates
			blog.json
	/embox
		/templates
			index.json
			404.json
			product.json
			cart.json
			collection.json
			blog.json
		/sections
			header-group.json
			footer-group.json
	/7th-street
		/templates
			index.json
			404.json
			product.json
			cart.json
			collection.json
			blog.json
		/sections
			header-group.json
			footer-group.json
/sections
/snippets
/templates
```

--------------------------------

### Start Shopify Liquid Language Server

Source: https://shopify.dev/docs/storefronts/themes/tools/cli/language-server

Starts the Shopify Liquid Language Server as a Shopify CLI theme command. Run this command in your terminal to launch the language server for code editing features.

```terminal
shopify theme language-server
```

--------------------------------

### settings_data.json example with presets

Source: https://shopify.dev/docs/storefronts/themes/store/success/updates

Example settings_data.json structure for a theme zip submission. The presets object must contain keys matching the preset names (Embiggen, Canine Gourmand, Zenful, Embox, 7th Street) and the current object holds the active settings. Preset names should use proper sentence case, be under 30 characters, and use 1-2 words; one preset must match the theme name.

```json
[
  {
    "current": {...},
    "presets": {
         "Embiggen": {...},
         "Canine Gourmand": {...},
         "Zenful": {...},
         "Embox": {...},
         "7th Street": {...},
    },
  }
]
```

--------------------------------

### Verify Shopify CLI installation with shopify version

Source: https://shopify.dev/docs/storefronts/themes/tools/cli/migrate

Verifies that Shopify CLI 3.0+ is installed correctly. The command returns a version number.

```sh
shopify version
```

--------------------------------

### Install Shopify AI Toolkit for Claude Code

Source: https://shopify.dev/docs/storefronts/themes/getting-started/create

Run this command in your terminal to install the Shopify AI Toolkit plugin for Claude Code.

```terminal
claude plugin install shopify-ai-toolkit@claude-plugins-official
```

--------------------------------

### Accessing resources with access paths

Source: https://shopify.dev/docs/storefronts/themes/architecture/blocks/theme-blocks/dynamic-sources

Examples of accessing template resources, section settings, and block settings using standard access paths.

```liquid
// Template resource
{{ product }}
{{ collection }}


// Section settings
{{ section.settings.featured_product }}


// Block settings
{{ block.settings.collection }}
```

--------------------------------

### Passing example: valid Liquid syntax

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/liquid-html-syntax-error

This example passes the check because it uses valid Liquid syntax with properly closed tags and correct filter syntax.

```liquid
<a>closed</a>
<Partial filePath="muffin" />
{% assign foo  = 1 %}
{% if collection.size > 0 %}{% endif %}
```

--------------------------------

### llms-full.txt.liquid template example using agents object

Source: https://shopify.dev/docs/storefronts/themes/architecture/templates/llms-full-txt-liquid

Example content for the llms-full.txt.liquid template. Uses the agents object to output store name, URL, UCP discovery, MCP endpoint, supported versions, and sitemap. Only the request and agents objects are available in this restricted Liquid context.

```liquid
# {{ agents.store_name }} — Full agent reference


The canonical description is at {{ agents.store_url }}/agents.md.


## Commerce Protocol (UCP)
- UCP discovery: {{ agents.ucp_discovery_url }}
- MCP endpoint: {{ agents.mcp_endpoint_url }}


### Supported UCP versions
{% for version in agents.ucp_versions %}
- {{ version }}
{% endfor %}


## Read-only browsing
- All products: `GET /collections/all`
- Sitemap: {{ agents.sitemap_url }}

```

--------------------------------

### Example llms.txt.liquid template using agents object

Source: https://shopify.dev/docs/storefronts/themes/architecture/templates/llms-txt-liquid

Example content for the llms.txt.liquid template. It uses the agents object to output store name, store URL, UCP discovery URL, MCP endpoint URL, and sitemap URL. The template renders with a restricted Liquid context where only the request and agents objects are available.

```liquid
# {{ agents.store_name }}


> Agent-discovery summary. The canonical, full description is at {{ agents.store_url }}/agents.md.


- UCP discovery: {{ agents.ucp_discovery_url }}
- MCP endpoint: {{ agents.mcp_endpoint_url }}
- Sitemap: {{ agents.sitemap_url }}
```

--------------------------------

### Render alternate template with view parameter

Source: https://shopify.dev/docs/storefronts/themes/architecture/templates/alternate-templates

URL to render the product 'Example product' with the alternate template 'product.alternate.json' using the 'view' URL parameter.

```text
/products/example-product?view=alternate
```

--------------------------------

### Fail: preset settings with invalid key

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-settings-key

Failing example for preset settings: the preset settings key 'fake-setting' does not exist in the section's settings schema, so the ValidSettingsKey check fails.

```liquid
{% schema %}
{
  "settings": {
    "type": "text",
    "id": "custom-setting",
    "label": "Custom Setting",
  },
  "presets": [{
    "name": "Preset",
    "settings": {
      "fake-setting": "not valid setting"
    }
  }]
}
{% endschema %}
```

--------------------------------

### Start a Local Development Server with shopify theme dev

Source: https://shopify.dev/docs/storefronts/themes/getting-started/create

Run `shopify theme dev --store my-store` to serve your theme. The `--store` flag is required the first time; the store is remembered for future commands. The preview URL is http://127.0.0.1:9292 and is only available in Google Chrome.

```terminal
shopify theme dev --store my-store
```

--------------------------------

### Before: asset URL with http://

Source: https://shopify.dev/docs/storefronts/themes/troubleshooting/use-protocol-independent-urls

Shows a link tag with an http:// URL for a Google Fonts stylesheet. This is the 'before' example that should be updated to use a protocol-independent URL.

```html
<link
  href="http://fonts.googleapis.com/css?family=Open+Sans"
  rel="stylesheet"
  type="text/css"
/>
```

--------------------------------

### Before: JavaScript-rendered collection grid

Source: https://shopify.dev/docs/storefronts/themes/best-practices/performance/render-essential-content-server-side

Before example: a placeholder div and a deferred script that fetches products and builds the grid client-side. Product images are not discoverable until the script executes.

```html
<div id="collection-grid"></div>
<script src="{{ 'collection-app.js' | asset_url }}" defer></script>
<!--
  JavaScript fetches products, builds card HTML for each one,
  and inserts the grid. No product images are discoverable
  until the script finishes executing.
-->
```

--------------------------------

### Example CSS link checked by AssetSizeCSS

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/asset-size-css

Example of a CSS file link that is checked by AssetSizeCSS to ensure it doesn't exceed the configured threshold_in_bytes.

```html
<link rel="stylesheet" href="{{ 'section-rich-text.css' | asset_url }}" media="print" onload="this.media='all'" />
```

--------------------------------

### Size guide modal with variant data

Source: https://shopify.dev/docs/storefronts/themes/best-practices/performance/defer-modal-content-loading

Liquid snippet for a size guide modal that conditionally loads variant-specific data. The `load_size_guide` parameter controls rendering, and the snippet accesses only the selected variant via `product.selected_or_first_available_variant` to display its size guide metafield. The comment emphasizes accessing only the selected variant, not all variants.

```liquid
{% doc %}
  @param {boolean} [load_size_guide] - Whether to load size guide data.
{% enddoc %}


<dialog id="size-guide-modal">
  {% if load_size_guide %}
    <table class="size-guide">
      <thead>
        <tr>
          <th>Size</th>
          <th>Measurements</th>
          <th>Available</th>
        </tr>
      </thead>
      <tbody>
        {%- comment -%} Access only the selected variant, not all variants {%- endcomment -%}
        {% assign variant = product.selected_or_first_available_variant %}
        {% if variant.metafields.custom.size_guide %}
          <tr>
            <td>{{ variant.option1 }}</td>
            <td>{{ variant.metafields.custom.size_guide.value }}</td>
            <td>{{ variant.available }}</td>
          </tr>
        {% endif %}
      </tbody>
    </table>
  {% endif %}
</dialog>
```

--------------------------------

### Example markets.json configuration

Source: https://shopify.dev/docs/storefronts/themes/architecture/config/markets-json

Example markets.json file for a theme with customizations for North America, Canada, United States, and Europe. The parent field can be set to @default or any parent market handle.

```json
/*
 * ------------------------------------------------------------
 * IMPORTANT: The contents of this file are auto-generated.
  *
 * This file may be updated by the Shopify admin theme editor
 * or related systems. Please exercise caution as any changes
 * made to this file may be overwritten.
 * ------------------------------------------------------------
  */
{
  "markets": {
    "europe": {
      "parent": "@default"
    },
  "north-america": {
      "parent": "@default"
    },
  "canada": {
      "parent": "north-america"
    },
  "united-states": {
      "parent": "north-america"
    }
  }
}
```

--------------------------------

### Example section group JSON file

Source: https://shopify.dev/docs/storefronts/themes/architecture/section-groups

Example of a section group JSON file with a `header` type, a name, a `sections` object containing a single section, and an `order` array.

```json
{
 "type": "header",
 "name": "Header Group",
 "sections": {
   "header": {
     "type": "header",
     "settings": {}
   }
 },
 "order": ["header"]
}
```

--------------------------------

### Example locale file structure

Source: https://shopify.dev/docs/storefronts/themes/architecture/locales

Shows the basic organizational structure of a locale file with categories, groups, and descriptions.

```json
{
  "my_category": {
    "my_group": {
      "my_description": "translation text",
      ...
    },
    ...
  },
  ...
}
```

--------------------------------

### Output: Hello Jane Doe!

Source: https://shopify.dev/docs/storefronts/themes/architecture/locales/storefront-locale-files

Output of the multiple-arguments example for a customer named Jane Doe.

```html
<h1>Hello Jane Doe!</h1>
```

--------------------------------

### After: asset URL with //

Source: https://shopify.dev/docs/storefronts/themes/troubleshooting/use-protocol-independent-urls

Shows the same link tag with the URL protocol changed to //, making it protocol-independent. This is the 'after' example that should be used.

```html
<link
  href="//fonts.googleapis.com/css?family=Open+Sans"
  rel="stylesheet"
  type="text/css"
/>
```

--------------------------------

### Fail: default settings with invalid key

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-settings-key

Failing example for default settings: the default settings key 'fake-setting' does not exist in the section's settings schema, so the ValidSettingsKey check fails.

```liquid
{% schema %}
{
  "settings": {
    "type": "text",
    "id": "custom-setting",
    "label": "Custom Setting",
  },
  "default": {
    "settings": {
      "fake-setting": "not valid setting"
    }
  }
}
{% endschema %}
```

--------------------------------

### Passing example: all arguments match types

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-content-for-argument-types

Passes the check because all arguments match the expected types. `shop` and `product` are global Liquid variables.

```liquid
{% content_for 'block',
  type: 'example-block',
  some_str: 'text',
  some_num: 1,
  some_bool: false,
  some_obj: shop,
  some_untyped: product
%}
```

--------------------------------

### .theme-check.yml configuration file

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/configuration

Example configuration file for Theme Check. Shows how to set the root directory, extend configurations, require custom checks, ignore paths, disable a check (TemplateLength), and enable a custom check (MyCustomCheck).

```yaml
# The directory where theme folders are located (optional)
root: dist


# Configuration files are extensible
extends:
  - theme-check:recommended # or theme-check:all, theme-check:theme-app-extension
  - '@acme/my-custom-checks/recommended.yml'
  - '../configs/.theme-check.yml'


# Paths to custom checks
require:
  - ./path/to/my_custom_check.js # path to file or module
  - '@acme/my-custom-checks'     # for node_modules checks


# Paths to ignore (don't lint those!)
ignore:
  - 'node_modules/**'
  - 'snippets/*-icon.liquid' # minimatch globs are supported


# Disable a check
TemplateLength:
  enabled: false
  severity: warning
  ignore:
    - templates/index.liquid
  # Configure options for a check
  max_length: 300


# Enable a custom check
MyCustomCheck:
  enabled: true
  severity: error

```

--------------------------------

### Sample block schema for block settings examples

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-settings-key

Sample block schema used in the preset block settings and default block settings examples. It defines a block setting with id 'block-setting'.

```liquid
{% schema %}
{
  "settings": {
    "type": "text",
    "id": "block-setting",
    "label": "Block Setting",
  }
}
{% endschema %}
```

--------------------------------

### Pass: preset settings with valid key

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-settings-key

Passing example for preset settings: the preset settings key 'custom-setting' matches the section's settings schema, so the ValidSettingsKey check passes.

```liquid
{% schema %}
{
  "settings": {
    "type": "text",
    "id": "custom-setting",
    "label": "Custom Setting",
  },
  "presets": [{
    "name": "Preset",
    "settings": {
      "custom-setting": "valid setting"
    }
  }]
}
{% endschema %}
```

--------------------------------

### Install Shopify AI Toolkit for Codex

Source: https://shopify.dev/docs/storefronts/themes/getting-started/create

Run this command in your terminal to add the Shopify plugin for Codex.

```terminal
codex plugin add shopify@openai-curated
```

--------------------------------

### Reference partials with get() and getAll()

Source: https://shopify.dev/docs/storefronts/themes/architecture/partials

Reference partials already on the page without fetching or replacing them. get() returns the first matching partial, and getAll() returns every partial in a scope. Each result pairs the partial name with a Range spanning its content.

```javascript
const grid = partials.get('product-grid');
const bounds = grid?.range.getBoundingClientRect();


const regions = partials.getAll(document.querySelector('main'));
```

--------------------------------

### Calculate bundle price with calculateBundlePrice

Source: https://shopify.dev/docs/storefronts/themes/product-merchandising/bundles-emails

Calculates the total price of a bundle by summing the prices of its components. Pass a bundle object (e.g., result[0]) to get the total; the example returns 22.0. Adjust the field used (e.g., discountedTotalSet or discountedUnitPriceSet) to match your query.

```javascript
function calculateBundlePrice(bundle) {
  return bundle.components.reduce((acc, component) => {
    return acc + parseFloat(component.price);
  }, 0);
}


calculateBundlePrice(result[0]); // 22.0
```

--------------------------------

### Translatable section name example

Source: https://shopify.dev/docs/storefronts/themes/architecture/locales/schema-locale-files

Example of making the name attribute of the product.liquid section translatable. The JSON file defines the translation, and the Liquid file references it using the t: syntax.

```json
{
  "sections": {
    "product": {
      "name": "Product"
    }
  }
}
```

```liquid
{% schema %}
{
  "name": "t:sections.product.name",
  ...
}
{% endschema %}
```

--------------------------------

### Liquid: After - responsive product image

Source: https://shopify.dev/docs/storefronts/themes/best-practices/performance/fix-content-wider-than-mobile-screen

This is the 'after' example showing a responsive image that scales to fit the viewport. It uses srcset with multiple widths, sizes, explicit width/height attributes, and inline style to ensure max-width: 100% and height: auto.

```liquid
<!-- Image scales to fit viewport -->
<img
  src="{{ product.featured_image | image_url: width: 1200 }}"
  srcset="
    {{ product.featured_image | image_url: width: 400 }} 400w,
    {{ product.featured_image | image_url: width: 800 }} 800w,
    {{ product.featured_image | image_url: width: 1200 }} 1200w
  "
  sizes="(max-width: 768px) 100vw, 50vw"
  width="{{ product.featured_image.width }}"
  height="{{ product.featured_image.height }}"
  alt="{{ product.title | escape }}"
  style="max-width: 100%; height: auto; display: block;"
>
```

--------------------------------

### Example settings_data.json structure

Source: https://shopify.dev/docs/storefronts/themes/architecture/config/settings-data-json

Shows the basic structure of the settings_data.json file with current and presets objects. The current object holds saved setting values, and presets contains objects for each theme preset.

```json
{
"current": {
  "color_page_bg": "#FFFFFF",
  ...
},
"presets": {
  "preset name": {
    "color_page_bg": "#000000",
    ...
  }
}
}
```

--------------------------------

### Output: Hello Jane!

Source: https://shopify.dev/docs/storefronts/themes/architecture/locales/storefront-locale-files

Output of the translation example showing the rendered heading with the customer's first name.

```html
<h1>Hello Jane!</h1>
```

--------------------------------

### Pass: Preconnect to example.com

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/cdn-preconnect

Passes the CdnPreconnect check because it preconnects to a non-Shopify domain, which is not redundant.

```liquid
<link href="https://example.com/" rel="preconnect" />
<link href="https://example.com/" rel="preconnect" crossorigin />
```

--------------------------------

### Pass: default settings with valid key

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-settings-key

Passing example for default settings: the default settings key 'custom-setting' matches the section's settings schema, so the ValidSettingsKey check passes.

```liquid
{% schema %}
{
  "settings": {
    "type": "text",
    "id": "custom-setting",
    "label": "Custom Setting",
  },
  "default": {
    "settings": {
      "custom-setting": "valid setting"
    }
  }
}
{% endschema %}
```

--------------------------------

### Initialize a New Theme with shopify theme init

Source: https://shopify.dev/docs/storefronts/themes/getting-started/create

Run `shopify theme init` in your working directory to clone the Skeleton theme. You will be prompted to enter a theme name, and the theme is cloned into a folder with that name.

```terminal
shopify theme init
```

--------------------------------

### Failing example: missing closing bracket

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/liquid-html-syntax-error

This example fails the check because it contains an unclosed tag and a missing closing bracket `%}`. It demonstrates common Liquid syntax errors that the check flags.

```liquid
<a>unclosed
{% include 'muffin'
{% assign foo = 1 }}
{% unknown %}
{% if collection | size > 0 %}
```

--------------------------------

### ValidSettingsKey check configuration

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-settings-key

Configuration example for the ValidSettingsKey check. It enables the check and sets its severity to error.

```yaml
ValidSettingsKey:
enabled: true
severity: error
```

--------------------------------

### Configuration for AppBlockMissingSchema

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/app-block-missing-schema

Configuration example for the AppBlockMissingSchema check. It sets the check to enabled with error severity.

```yaml
AppBlockMissingSchema:
enabled: true
severity: error
```

--------------------------------

### Example 404 template HTML with Liquid link

Source: https://shopify.dev/docs/storefronts/themes/architecture/templates/404

Example HTML for a 404 template that displays a 404 message, a 'Page not found' heading, and a 'Continue shopping' link using the Liquid route `routes.all_products_collection_url`. If using a JSON template, this code must be included in a section referenced by the template.

```html
<p>
  404
</p>
<h1 className="title">
  Page not found
</h1>
<a href="{{ routes.all_products_collection_url }}" className="button">
  Continue shopping
</a>
```

--------------------------------

### Pass: preset block settings with valid key

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-settings-key

Passing example for preset block settings: the preset block settings key 'block-setting' matches the referenced block's schema, so the ValidSettingsKey check passes.

```liquid
{% schema %}
{
  "blocks": [{ "type": "example-block" }],
  "presets": [{
    "name": "Preset",
    "blocks": [{
      "type": "example-block",
      "settings": {
        "block-setting": "valid setting in example-block"
      }
    }]
  }]
}
{% endschema %}
```

--------------------------------

### Pass: both required and optional arguments provided

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/missing-content-for-arguments

Passing example: provides both the required argument `some_str` and the optional argument `some_num`.

```liquid
{% content_for 'block', type: 'example-snippet', some_str: 'text', some_num: 1 %}
```

--------------------------------

### Create a dev store with Shopify CLI

Source: https://shopify.dev/docs/storefronts/themes/tools/development-stores

Creates a new dev store using Shopify CLI. Pass --feature-preview with a preview handle to enable a preview, and --with-demo-data to populate the store with test data.

```bash
shopify store create dev
```

--------------------------------

### Configure Theme Check asset size thresholds in .theme-check.yml

Source: https://shopify.dev/docs/storefronts/themes/best-practices/performance/theme-check-tool

Create a `.theme-check.yml` file to enable asset size checks and customize thresholds. Setting names are camelCase; unrecognized names like `threshold_in_bytes` log an `Unexpected setting` warning and are ignored.

```yaml
AssetSizeCSS:
  enabled: true
  thresholdInBytes: 100000

AssetSizeJavaScript:
  enabled: true
  thresholdInBytes: 10000

PaginationSize:
  enabled: true
  maxSize: 250
```

--------------------------------

### Passing example: variable arguments

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-content-for-argument-types

Passes the check because variables always pass this check.

```liquid
{% assign some_var = 'text' %}
{% content_for 'block',
  type: 'example-block',
  some_str: some_var,
  some_num: some_var,
  some_bool: some_var,
  some_obj: some_var,
  some_untyped: some_var
%}
```

--------------------------------

### Passing example: recognized arguments in content_for

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/unrecognized-content-for-arguments

Renders the static block with only the recognized arguments 'some_str' and 'some_num', which passes the check.

```liquid
{% content_for 'block', type: 'example-block', some_str: 'text', some_num: 1 %}
```

--------------------------------

### Pass: valid named arguments

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-content-for-arguments

Passing example: all named attributes are accepted by the `content_for` tag.

```liquid
{% content_for "blocks" %}
{% content_for "blocks", context.product: product %}
{% content_for "block", type: "slide", id: "my-static-slide" %}
{% content_for "block", type: "slide", id: "my-static-slide", context.product: product %}
```

--------------------------------

### Sort collection by price-descending URL

Source: https://shopify.dev/docs/storefronts/themes/architecture/templates/collection

Example URL for sorting products in a collection using the sort_by parameter.

```text
https://my-store.myshopify.com/collections/frontpage?sort_by=price-descending
```

--------------------------------

### Product JSON template with sections and order

Source: https://shopify.dev/docs/storefronts/themes/architecture/templates/json-templates

Example of a product.json template that defines two sections: a product section with a setting to show the vendor, and a product-recommendations section. The order array controls the rendering order. Any non-app sections referenced must exist in the theme, otherwise an error occurs.

```json
{
  "sections": {
    "main": {
      "type": "product",
      "settings": {
        "show_vendor": true
      }
    },
    "recommendations": {
      "type": "product-recommendations"
    }
  },
  "order": [
    "main",
    "recommendations"
  ]
}
```

--------------------------------

### LiquidDoc block with optional parameters

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-content-for-argument-types

Defines the LiquidDoc block with optional parameters used by all examples in this check.

```liquid
{% doc %}
  @param {string} [some_str]
  @param {number} [some_num]
  @param {boolean} [some_bool]
  @param {object} [some_obj]
  @param [some_untyped]
{% enddoc %}
```

--------------------------------

### Pass: All translation keys defined

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-schema-translations

Passing example: every t: key used in the schema (name, label, info) has a matching entry in the default schema locale file.

```liquid
{% schema %}
{
  "name": "t:sections.header.name",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "t:sections.header.settings.title.label",
      "info": "t:sections.header.settings.title.info"
    }
  ]
}
{% endschema %}
```

```json
{
  "sections": {
    "header": {
      "name": "Header",
      "settings": {
        "title": {
          "label": "Title",
          "info": "Enter a title"
        }
      }
    }
  }
}
```

--------------------------------

### Pass: Assigning a variable before use

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/undefined-object

This example passes the check because the variable is assigned with `assign` before it is used.

```liquid
{% assign my_variable = "Hello" %}
{{ my_variable }}
```

--------------------------------

### Filter URL parameter examples

Source: https://shopify.dev/docs/storefronts/themes/navigation-search/filtering/storefront-filtering

Shows two ways to specify multiple values for the same filter parameter: comma-separated and repeated parameters.

```text
filter.v.option.color=red,blue
filter.v.option.color=red&filter.v.option.color=blue
```

--------------------------------

### Use section.index for conditional loading

Source: https://shopify.dev/docs/storefronts/themes/best-practices/performance/never-lazy-load-lcp-image

Use section.index to conditionally set loading and fetchpriority. The first section gets eager and high fetchpriority, sections 4+ get lazy, and sections 2-3 (or when section.index is nil) get eager. Test the lazy case as a positive comparison (section.index > 3) to handle nil correctly.

```liquid
{% if section.index == 1 %}
  {%- comment -%} First section: eager, and the LCP candidate {%- endcomment -%}
  {{ image
    | image_url: width: 1000
    | image_tag:
        loading: 'eager',
        fetchpriority: 'high'
  }}
{% elsif section.index > 3 %}
  {%- comment -%} Sections 4 and later {%- endcomment -%}
  {{ image
    | image_url: width: 1000
    | image_tag: loading: 'lazy'
  }}
{% else %}
  {%- comment -%} Sections 2 and 3, and any context where section.index is nil {%- endcomment -%}
  {{ image
    | image_url: width: 1000
    | image_tag: loading: 'eager'
  }}
{% endif %}
```

--------------------------------

### Less performant: repeated block.settings access

Source: https://shopify.dev/docs/storefronts/themes/best-practices/performance/assign-block-settings-to-variable

Less performant example that accesses block.settings multiple times directly. Use the assign pattern to improve performance.

```liquid
<h2>{{ block.settings.title }}</h2>
<p>{{ block.settings.text }}</p>
<a href="{{ block.settings.link_url }}">{{ block.settings.link_text }}</a>
{% if block.settings.show_image and block.settings.image != blank %}
  {{ block.settings.image | image_url: width: 600 | image_tag: loading: 'lazy' }}
{% endif %}
```

--------------------------------

### Fail: preset block settings with invalid key

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-settings-key

Failing example for preset block settings: the preset block settings key 'fake-setting' does not exist in the referenced block's schema, so the ValidSettingsKey check fails.

```liquid
{% schema %}
{
  "blocks": [{ "type": "example-block" }],
  "presets": [{
    "name": "Preset",
    "blocks": [{
      "type": "example-block",
      "settings": {
        "fake-setting": "not valid setting in example-block"
      }
    }]
  }]
}
{% endschema %}
```

--------------------------------

### Fail: default block settings with invalid key

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-settings-key

Failing example for default block settings: the default block settings key 'fake-setting' does not exist in the referenced block's schema, so the ValidSettingsKey check fails.

```liquid
{% schema %}
{
  "blocks": [{ "type": "example-block" }],
  "default": {
    "name": "Preset",
    "blocks": [{
      "type": "example-block",
      "settings": {
        "fake-setting": "not valid setting in example-block"
      }
    }]
  }
}
{% endschema %}
```

--------------------------------

### Pass: default block settings with valid key

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-settings-key

Passing example for default block settings: the default block settings key 'block-setting' matches the referenced block's schema, so the ValidSettingsKey check passes.

```liquid
{% schema %}
{
  "blocks": [{ "type": "example-block" }],
  "default": {
    "name": "Preset",
    "blocks": [{
      "type": "example-block",
      "settings": {
        "block-setting": "valid setting in example-block"
      }
    }]
  }
}
{% endschema %}
```

--------------------------------

### List extension bundles by size and load time using performance.getEntriesByType

Source: https://shopify.dev/docs/storefronts/themes/best-practices/performance/optimize-checkout-extensions

Run in the DevTools Console on a loaded checkout to produce a sortable table of extension assets fetched, showing asset name, transfer size, decoded size, start time, and duration, sorted by decoded size. transferKB will be 0 for cross-origin assets without timing headers, so compare decodedKB instead; assets fetched inside an extension's sandbox will not appear, so if the table is empty or short, use the Network panel filtered on 'extensions'.

```javascript
console.table(
  performance
    .getEntriesByType('resource')
    .filter((entry) => entry.name.includes('/extensions/'))
    .map((entry) => ({
      asset: entry.name.split('?')[0].split('/').slice(-2).join('/'),
      transferKB: Math.round(entry.transferSize / 1024),
      decodedKB: Math.round(entry.decodedBodySize / 1024),
      startedAtMs: Math.round(entry.startTime),
      durationMs: Math.round(entry.duration),
    }))
    .sort((first, second) => second.decodedKB - first.decodedKB),
);
```

--------------------------------

### Pass: All LiquidDoc parameters used

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/unused-doc-param

Passing example: all LiquidDoc parameters (`some_str`, `some_num`, `some_bool`) are used within the snippet, so the check passes.

```liquid
{% doc %}
  @param {string} some_str
  @param {number} some_num
  @param {boolean} some_bool
{% enddoc %}


<div className="css-{{ some_str }}"></div>


{% if some_bool %}
  {{ some_num | plus 5 }}
{% endif %}
```

--------------------------------

### Basic layout example with content_for_header and content_for_layout

Source: https://shopify.dev/docs/storefronts/themes/architecture/layouts

Basic layout file structure for Shopify themes. It includes the required Liquid objects `content_for_header` inside the `<head>` tag and `content_for_layout` between `<body>` and `</body>`. These objects are required in `theme.liquid`; omitting them prevents saving or updating the file using the code editor or Shopify CLI.

```liquid
<!DOCTYPE html>
<html>
  <head>
    ...
    {{ content_for_header }}
    ...
  </head>


  <body>
    ...
    {{ content_for_layout }}
    ...
  </body>
 </html>
```

--------------------------------

### Number setting example

Source: https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings

Defines a number input setting in settings_schema.json. The default value must be a number, not a string, or an error occurs. The placeholder attribute is only supported in settings_schema.json, not in section schemas.

```json
{
  "type": "number",
  "id": "products_per_page",
  "label": "Products per page",
  "default": 20
}
```

--------------------------------

### Initialize Shopify-XR library

Source: https://shopify.dev/docs/storefronts/themes/product-merchandising/media/support-media

Include this JavaScript on product pages to initialize the Shopify-XR library. It listens for the 'shopify_xr_initialized' event and adds models from the product media.

```JavaScript
<script>
function setupShopifyXr(){
  if (!window.ShopifyXR) {
    document.addEventListener('shopify_xr_initialized', function() {
      setupShopifyXr();
    });
  }else{
    {% assign models = product.media | where: 'media_type', 'model' | json -%}
    window.ShopifyXR.addModels({{ models }});
    window.ShopifyXR.setupXRElements();
  }
}


window.Shopify.loadFeatures([
  {
    name: 'shopify-xr',
    version: '1.0',
    onLoad: setupShopifyXr
  }
]);
</script>
```

--------------------------------

### Before: Client-side framework with empty container

Source: https://shopify.dev/docs/storefronts/themes/best-practices/performance/render-essential-content-server-side

Shows the initial HTML with an empty container and a deferred script bundle. The browser cannot display content or discover the product image until the JavaScript bundle loads, parses, executes, fetches data from the Storefront API, and builds the DOM.

```html
<!-- The server sends an empty container -->
<div id="product-root"></div>
<script src="{{ 'product-app.bundle.js' | asset_url }}" defer></script>
<script>
  // After the bundle loads, parses, and executes:
  // 1. Fetch product data from the Storefront API
  // 2. Build the DOM from the response
  // 3. Insert it into #product-root
  // The browser can't display anything or discover the product image until this completes.
</script>
```

--------------------------------

### Pass: Using CSS image-set() attribute

Source: https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/deprecate-bgsizes

Passing example that uses the CSS `image-set()` attribute instead of `data-bgset`. Includes both the CSS stylesheet and the HTML markup.

```html
<!-- CSS Stylesheet -->
.box {
  background-image: -webkit-image-set(
    url("small-balloons.jpg") 1x,
    url("large-balloons.jpg") 2x);
  background-image: image-set(
    url("small-balloons.jpg") 1x,
    url("large-balloons.jpg") 2x);
}


<!-- HTML -->
<div className="box"></div>
```

--------------------------------

### Streaming-optimized layout head example

Source: https://shopify.dev/docs/storefronts/themes/best-practices/performance/load-critical-resources-before-content-for-header

A complete layout/theme.liquid head structure used by Horizon, with snippets inlined. It includes preloaded fonts, stylesheet preload, an import map, modulepreload, a module script, a design-mode script, and content_for_header. This arrangement keeps the head cheap and avoids expensive Liquid loops.

```liquid
<!doctype html>
<html lang="{{ request.locale.iso_code }}">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ page_title }}</title>
    <link rel="canonical" href="{{ canonical_url }}">


    {%- unless settings.type_body_font.system? -%}
      {{ settings.type_body_font | font_url | preload_tag: as: 'font', type: 'font/woff2' }}
    {%- endunless -%}


    {{ 'base.css' | asset_url | stylesheet_tag: preload: true }}


    {% style %}
      {{ settings.type_body_font | font_face: font_display: 'swap' }}
      :root {
        --color-background: {{ settings.color_background }};
        --font-body-family: {{ settings.type_body_font.family }}, {{ settings.type_body_font.fallback_families }};
      }
    {% endstyle %}


    <script type="importmap">
      {
        "imports": {
          "@theme/utilities": "{{ 'utilities.js' | asset_url }}"
        }
      }
    </script>
    <link rel="modulepreload" href="{{ 'utilities.js' | asset_url }}">
    <script src="{{ 'global.js' | asset_url }}" type="module"></script>


    {% if request.design_mode %}
      <script src="{{ 'theme-editor.js' | asset_url }}" defer></script>
    {% endif %}


    {{ content_for_header }}
  </head>
  <body>
    {% sections 'header-group' %}
    <main id="MainContent">
      {{ content_for_layout }}
    </main>
    {% sections 'footer-group' %}
  </body>
</html>
```