Render essential content in Liquid and HTML, not JavaScript

Render initial content with Liquid and HTML instead of client-side frameworks. Use server-side rendering (Hydrogen) if frameworks are required, not client-side frameworks on Liquid storefronts.

Anchor to WhyWhy

When a browser receives server-rendered HTML, it can paint content and discover resources immediately. The preload scanner reads through HTML as it arrives and starts fetching images, stylesheets, and fonts before the page finishes loading. This is the fastest path to visible content.

Client-side JavaScript frameworks bypass this entirely. Instead of receiving ready-to-display HTML, the browser receives an empty shell and must complete a sequential chain before the user sees anything:

Download the HTML document (which contains little or no visible content).
Parse the HTML and discover the framework's JavaScript bundle.
Download, parse, and execute the JavaScript bundle.
The framework makes data-fetching requests (to the Storefront API or other endpoints).
After data returns, the framework renders content into the DOM.
Only now can the browser discover images and other resources that the rendered content references.

Each step in this chain depends on the previous step completing. The result is a long sequential waterfall where the browser sits idle, waiting, while the user stares at a blank or skeleton page.

This waterfall directly harms three Core Web Vitals metrics:

FCP (First Contentful Paint): Nothing renders until the framework finishes executing and inserting content. With server-rendered HTML, the browser paints content as soon as it parses the HTML.
LCP (Largest Contentful Paint): The LCP image can't be discovered until after JavaScript renders the img element into the DOM. The preload scanner never sees it because it wasn't in the original HTML.
INP (Interaction to Next Paint): Large JavaScript bundles consume main-thread time during parsing and execution. While the main thread is busy with framework code, user interactions (taps, clicks, scrolls) are delayed or unresponsive.

Anchor to HowHow

Anchor to Use Liquid for initial page contentUse Liquid for initial page content

Render the initial view of every page with Liquid and HTML. When the server responds with complete HTML, the browser displays content immediately and the preload scanner discovers all referenced resources in the markup.

Before: A client-side framework fetches product data and renders it with JavaScript.

// 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>

After: Liquid renders the product directly into HTML. The browser displays the product image and text as soon as it parses the response.

{{ product.featured_image

| image_url: width: 1200

| image_tag:

loading: 'eager',

fetchpriority: 'high',

widths: '400, 600, 800, 1200',

sizes: '(min-width: 1000px) 600px, calc(100vw - 2rem)'

}}

</div>

<h1>{{ product.title }}</h1>

<p class="product__price">{{ product.selected_or_first_available_variant.price | money }}</p>

<div class="product__description">{{ product.description }}</div>

</div>

In the Liquid version, the product image URL is present in the HTML from the start. The preload scanner discovers it immediately and begins downloading the image in parallel with other page resources. No JavaScript needs to execute first.

Anchor to Layer JavaScript progressivelyLayer JavaScript progressively

Start with server-rendered content, then add interactivity on top. The initial HTML works without JavaScript. JavaScript enhances the experience when it loads.

This approach is called progressive enhancement. The server-rendered HTML provides the baseline experience, and JavaScript adds interactive features, such as variant switching, quantity selectors, and add-to-cart behavior.

{%- comment -%}

Server-rendered product form. The form, price, image, and buy button

are all present in the HTML, so the content is visible before any

JavaScript runs. JavaScript enhances option switching on top of it.

{%- endcomment -%}

{{ product.selected_or_first_available_variant.image

| default: product.featured_image

| image_url: width: 1200

| image_tag:

loading: 'eager',

fetchpriority: 'high',

widths: '400, 600, 800, 1200',

sizes: '(min-width: 1000px) 600px, calc(100vw - 2rem)',

id: 'product-image'

}}

</div>

<h1>{{ product.title }}</h1>

</p>

{%- comment -%}

Render the picker from `product.options_with_values`. Looping

`product.variants` truncates at 250 variants and costs render time on

every request. See "Avoid over-fetching product variants".

{%- endcomment -%}

{%- for option in product.options_with_values -%}

<legend>{{ option.name }}</legend>

{%- for option_value in option.values -%}

<input

id="{{ section.id }}-{{ option.position }}-{{ forloop.index0 }}"

type="radio"

name="{{ section.id }}-{{ option.name }}-{{ option.position }}"

value="{{ option_value | escape }}"

{% if option_value.selected %}checked{% endif %}

{% unless option_value.available %}disabled{% endunless %}

data-option-value-id="{{ option_value.id }}"

</label>

{%- endfor -%}

</fieldset>

{%- endfor -%}

</div>

{% form 'product', product %}

{%- comment -%}

The selected variant is resolved on the server, so the form posts a

single ID instead of listing every variant.

{%- endcomment -%}

<input

type="hidden"

name="id"

id="variant-id"

value="{{ product.selected_or_first_available_variant.id }}"

Add to cart

</button>

{% endform %}

</div>

The JavaScript that enhances this form is small and targeted. It asks the server to re-render the section for the newly selected option values, then swaps in the returned HTML. It doesn't render any of the initial content, and it doesn't need variant data in the page:

// product-form.js - enhances the server-rendered form

const productElement = document.querySelector('.product');

// Listen on the container that survives the swap, so the handler still works

// after the picker markup is replaced.

productElement.addEventListener('change', async (event) => {

// Scope to the picker that fired the event: a document-wide lookup returns

// the wrong section when a page renders more than one product.

const selectors = event.target.closest('.option-value-selectors');

if (!selectors) return;

const sectionId = selectors.dataset.sectionId;

const optionValues = Array.from(

selectors.querySelectorAll('input[type="radio"]:checked'),

)

.map(({dataset}) => dataset.optionValueId)

.join(',');

const response = await fetch(

`${window.location.pathname}?section_id=${sectionId}&option_values=${optionValues}`,

);

const html = new DOMParser().parseFromString(

await response.text(),

'text/html',

);

// The server returns the updated price, image, option availability, and

// variant ID, so the browser doesn't need any variant data.

const selectedId = event.target.id;

productElement.innerHTML = html.querySelector('.product').innerHTML;

// Replacing the markup discards focus, so restore it on the option the

// buyer selected.

document.getElementById(selectedId)?.focus();

});

Anchor to Use the Section Rendering API for dynamic updatesUse the Section Rendering API for dynamic updates

When content needs to change after the initial page load, use the Section Rendering API to fetch server-rendered HTML fragments instead of building DOM with JavaScript. The server renders the updated section with Liquid and returns the complete HTML. Your JavaScript replaces the existing section content with the server's response.

This keeps your rendering logic in Liquid where it belongs. The server handles the data and the templates. JavaScript handles fetching and swapping the HTML.

// Fetch a server-rendered section with a different variant selected

async function updateSection(sectionId, variantId) {

const url = `${window.location.pathname}?variant=${variantId}&sections=${sectionId}`;

const response = await fetch(url);

const data = await response.json();

const html = data[sectionId];

// Sections that fail to render come back as `null` inside a `200` response.

if (!html) return;

// The response is the full `shopify-section` wrapper, so replace the wrapper.

// Writing it into an inner element nests a second wrapper and duplicates its ID.

document.getElementById(`shopify-section-${sectionId}`).outerHTML = html;

}

This approach provides several advantages over client-side rendering:

Rendering logic stays in a single place (Liquid templates).
The server handles data access, so the browser doesn't need API keys or complex data-fetching code.
The HTML response is ready to display. No parsing, no template compilation, no virtual DOM diffing.
The JavaScript you ship is minimal: just fetch and DOM replacement.

For more detail, see Use the Section Rendering API for dynamic updates.

Anchor to ExamplesExamples

Anchor to Example 1: Product page rendered with Liquid instead of JavaScriptExample 1: Product page rendered with Liquid instead of JavaScript

Before: JavaScript fetches product data and renders the entire product display.

<!--

Load timeline:

1. Browser receives empty <div>

2. Downloads ~80-200 KB of JavaScript (framework + app)

3. Parses and executes JavaScript

4. JavaScript fetches product data from the Storefront API

5. JavaScript renders the product into #product-app

6. Browser discovers the product image for the first time

7. Browser downloads the product image

-->

After: Liquid renders the product. The image and content are in the initial HTML. The option picker uses product.options_with_values, so the page doesn't load every variant, and JavaScript adds option switching through the Section Rendering API.

{{ product.featured_image

| image_url: width: 1200

| image_tag:

loading: 'eager',

fetchpriority: 'high',

widths: '400, 600, 800, 1200',

sizes: '(min-width: 1000px) 600px, calc(100vw - 2rem)'

}}

</div>

<h1>{{ product.title }}</h1>

</p>

<div class="product__description">{{ product.description }}</div>

{%- for option in product.options_with_values -%}

<legend>{{ option.name }}</legend>

{%- for option_value in option.values -%}

<input

id="{{ section.id }}-{{ option.position }}-{{ forloop.index0 }}"

type="radio"

name="{{ section.id }}-{{ option.name }}-{{ option.position }}"

value="{{ option_value | escape }}"

{% if option_value.selected %}checked{% endif %}

{% unless option_value.available %}disabled{% endunless %}

data-option-value-id="{{ option_value.id }}"

</label>

{%- endfor -%}

</fieldset>

{%- endfor -%}

</div>

{% form 'product', product %}

<input

type="hidden"

name="id"

value="{{ product.selected_or_first_available_variant.id }}"

{% endform %}

</div>

</section>

<!--

Load timeline:

1. Browser receives complete HTML with product content and image URL

2. Preload scanner discovers the product image immediately

3. Browser starts downloading the image while still parsing the rest of the page

4. Content is painted at FCP

5. Small enhancement script loads and adds variant switching

-->

Anchor to Example 2: Collection gridExample 2: Collection grid

Before: JavaScript fetches the collection and renders a product grid.

<!--

JavaScript fetches products, builds card HTML for each one,

and inserts the grid. No product images are discoverable

until the script finishes executing.

-->

After: Liquid renders the grid. Filtering and sorting use the Section Rendering API to fetch updated server-rendered HTML.

{% paginate collection.products by 24 %}

{% for filter in collection.filters %}

<summary>{{ filter.label }}</summary>

<ul>

{% for value in filter.values %}

<li>

<label>

<input

type="checkbox"

name="{{ value.param_name }}"

value="{{ value.value }}"

{% if value.active %}checked{% endif %}

data-filter-input

{{ value.label }} ({{ value.count }})

</label>

</li>

{% endfor %}

</ul>

</details>

{% endfor %}

</form>

{% for product in collection.products %}

{%- liquid

if forloop.index <= 4

assign image_loading = 'eager'

else

assign image_loading = 'lazy'

endif

-%}

{{ product.featured_image

| image_url: width: 400

| image_tag:

loading: image_loading,

widths: '200, 300, 400',

sizes: '(min-width: 1200px) calc(25vw - 2rem), (min-width: 768px) calc(33vw - 2rem), calc(50vw - 2rem)'

}}

<h3>{{ product.title }}</h3>

<p>{{ product.price | money }}</p>

</div>

{% endfor %}

</div>

</div>

</section>

{% endpaginate %}

When a customer selects a filter, JavaScript fetches the updated grid from the Section Rendering API:

// collection-filters.js

document.querySelectorAll('[data-filter-input]').forEach((input) => {

input.addEventListener('change', async () => {

const form = document.querySelector('.collection__filters');

const params = new URLSearchParams(new FormData(form));

const sectionId = document.querySelector('.collection').dataset.sectionId;

params.set('sections', sectionId);

const response = await fetch(`${window.location.pathname}?${params}`);

const data = await response.json();

const tempDiv = document.createElement('div');

tempDiv.innerHTML = data[sectionId];

const newGrid = tempDiv.querySelector('#collection-products');

document.getElementById('collection-products').replaceWith(newGrid);

});

The server handles filtering and returns a fully rendered grid. The browser doesn't need product data, template logic, or a rendering framework.

Anchor to Example 3: Diagnose whether your site relies on JavaScript for renderingExample 3: Diagnose whether your site relies on JavaScript for rendering

To check whether essential content depends on JavaScript:

Open the site in Chrome.
Open DevTools: Command+Option+I on macOS, or Control+Shift+I on Windows.
Open the Command Menu: Command+Shift+P on macOS, or Control+Shift+P on Windows.
Type Disable JavaScript and select the option.
Reload the page.

If the page is blank or missing its primary content, such as product images, titles, prices, or navigation, then the site relies on client-side JavaScript for rendering. Move this content to Liquid templates so that it's present in the server-rendered HTML.

Also look for framework-specific patterns that hide content until JavaScript initializes:

x-cloak (Alpine.js) and v-cloak (Vue): These attributes hide elements until the framework initializes. If any are above the fold, then users on slow connections see blank space. Check: document.querySelectorAll('[x-cloak]').
JS-bound image attributes: Alpine's :loading="..." or Vue's v-bind:loading set the loading attribute dynamically. Without the framework, these images have no loading attribute, so the preload scanner can't determine their priority.
JS-triggered visibility: Images rendered with opacity: 0 that use JavaScript to fade in delay LCP. The image downloads, but the browser can't record the LCP event until the element is visible.

Anchor to TestingTesting

Disable JavaScript test: Follow the diagnosis steps in Example 3. Every piece of content visible in the initial viewport should render without JavaScript.
Performance panel waterfall: Record a performance trace in Chrome DevTools. Compare the time between navigation start and FCP. Server-rendered pages show content appearing early. JavaScript-rendered pages show a long gap where the main thread is busy executing scripts before any content appears.
Network panel resource discovery: Check when the LCP image request appears in the Network panel waterfall. On a server-rendered page, it appears early, because the preload scanner discovers it during HTML parsing. On a JavaScript-rendered page, it appears late, after the framework bundle finishes executing.
Compare bundle sizes: Check the total JavaScript payload in the Network panel. Server-rendered pages with progressive enhancement typically ship far less JavaScript than pages that depend on a client-side framework for rendering.

Anchor to ReferencesReferences

Was this page helpful?