November 5, 2026 · 8 min read

Custom Liquid Section Performance: LCP, Theme Inspector, and section:load Re-initialization

Learn how to audit and fix LCP in custom Liquid sections using Theme Inspector flame graphs, section.index loading strategy, and safe section:load

Custom Liquid Section Performance: LCP, Theme Inspector, and section:load Re-initialization

Custom Liquid sections are the most common source of LCP regressions in Shopify themes. The root causes are almost always one of three things: a hero image that gets lazy-loaded by accident, a Liquid template that burns server time in a loop, or JavaScript that only runs once on DOMContentLoaded and silently breaks inside the theme editor. All three are fixable once you know where to look.

Key takeaways

  • Shopify's image_tag filter auto-applies loading="lazy" for sections beyond position 3, so your hero must override this with section.index.
  • The Theme Inspector flame graph (version 3.0.2 on the Chrome Web Store, updated January 2025) exposes per-line Liquid cost. Target under 200ms total; treat anything over 500ms as a P1.
  • shopify:section:load fires every time a section is added or re-rendered in the editor. It is not a substitute for DOMContentLoaded.
  • Stacked event listeners are the most common editor crash pattern. Always store your handler in a named variable and remove it inside shopify:section:unload.
  • section.index and section.location let you branch loading strategy at render time, without any merchant-visible settings toggle.

Why custom sections hurt LCP more than built-in ones

Shopify's official performance docs, expanded over a 10-month period that wrapped up in late 2025 under web performance engineer Dan Gayle, are explicit about this: correct image loading strategy has a direct effect on LCP for most storefronts. The problem is that theme authors writing custom sections from scratch often skip the loading-strategy branching that Dawn and Horizon handle automatically.

Specific numbers from field data are worth anchoring to. The average Shopify store sits at 3.0 to 4.5 seconds on mobile LCP. Google's threshold for "Good" is under 2.5 seconds. Stores at 2.5-second LCP reportedly see roughly 30% higher conversion than stores at 3.5 seconds, according to Shopify's own published figures. Those gaps are real, and they come disproportionately from above-the-fold sections written by developers who focused on features, not loading order.

Step 1: Identify the offender with Theme Inspector

Shopify Theme Inspector for Chrome (the official Shopify-built extension, currently at version 3.0.2) renders a flame graph of server-side Liquid execution. Install it, sign in with your Shopify credentials, load any page on your development store, and click the extension icon.

What you see is a timeline where each node represents a Liquid file or block. Node width is proportional to render time. The key reads:

  • Time - how long that node (plus its children) took on the server.
  • Percentage - that node's share of total render time.
  • Sandwich view - groups every call to the same filter or tag so you can see cumulative cost from repeated calls.

Shopify's guidance is to aim for 200ms total, with 500ms as the hard ceiling. I have seen a custom collection section on a 10,000+ SKU catalog go from 480ms to 61ms purely by lifting a metafield lookup out of a product loop. The flame graph made the loop obvious in under two minutes.

Common flame graph patterns to watch for

  • A section node that is visually wider than the layout/theme.liquid node usually means you have a Liquid loop with per-iteration API calls.
  • A filter:image_url node appearing hundreds of times in sandwich view means you are calling the filter inside a loop without storing the result. Each call is cheap (around 50 microseconds) but 2,000 of them add 100ms quietly.
  • Anything that is wide but has no visible children is usually an unbounded for product in collection.products loop, which triggers a full product load per iteration.
{%- comment -%} Bad: N+1 metafield fetch inside a loop {%- endcomment -%}
{%- for product in collection.products -%}
  {{ product.metafields.custom.badge.value }}
{%- endfor -%}

{%- comment -%} Better: lift out of loop, cache in assign {%- endcomment -%}
{%- assign badge_map = '' -%}
{%- for product in collection.products -%}
  {%- assign badge = product.metafields.custom.badge.value -%}
  {%- if badge != blank -%}...{%- endif -%}
{%- endfor -%}

Step 2: Fix LCP with section.index and fetchpriority

The single most damaging mistake in a custom hero section is adding loading="lazy" to the banner image. Shopify's data showed that 82% of Shopify pages were lazy-loading their LCP image at one point. Removing loading="lazy" from a header image improved LCP by 0.5 seconds in a WebPageTest comparison Shopify published on performance.shopify.com.

Shopify's Liquid API provides two properties to handle this correctly without a merchant-facing toggle:

  • section.index - 1-based position of the section within its location (template, header, footer, etc.).
  • section.index0 - same, but 0-based.
  • section.location - the scope string (template, header, footer, or a custom section group name).

Note: section.index returns nil for static sections (those hardcoded in theme.liquid rather than included via a JSON template), so always guard against nil in conditional logic.

Here is a correct loading strategy for a custom image-banner section:

{%- liquid
  assign loading_strategy = 'lazy'
  assign fetch_priority = 'auto'

  if section.index == 1
    assign loading_strategy = 'eager'
    assign fetch_priority = 'high'
  elsif section.index <= 3
    assign loading_strategy = 'eager'
  endif
-%}

{%- if section.index == 1 -%}
  <link
    rel="preload"
    as="image"
    href="{{ section.settings.image | image_url: width: 1200 }}"
    fetchpriority="high"
  >
{%- endif -%}

{{ section.settings.image
  | image_url: width: 1500
  | image_tag:
    loading: loading_strategy,
    fetchpriority: fetch_priority,
    width: section.settings.image.width,
    height: section.settings.image.height
}}

Shopify's official performance docs label "never lazy-load the LCP image" as a High-priority recommendation, alongside "mark the LCP image with fetchpriority="high"". The preload link in theme.liquid (or in the section's own {% style %} block when you know the section is first) pulls the image into the browser's preload scanner before Liquid even finishes rendering the rest of the page.

Image loading strategy by section position

section.index valueRecommended loadingRecommended fetchpriorityNotes
1eagerhighHero or banner. Add <link rel="preload">.
2 or 3eagerautoAbove fold on most viewports.
4 or higherlazyautoDefault image_tag behavior already does this.
nil (static section)eager or hardcodeautosection.index is unavailable; use a section setting instead.

For sections that render a grid of images (product cards, collection tiles), combine section.index with forloop.index: eager-load the first row, lazy-load everything below.

Step 3: section:load re-initialization without stacking listeners

This is the part most tutorials skip. When a merchant edits a section setting in the theme editor, Shopify re-renders the entire section HTML and fires shopify:section:load. As Shopify's own docs put it, the event fires when "a section has been added or re-rendered" and you should "re-execute any JavaScript needed for the section to work and display properly, as if the page had just been loaded."

The problem is that the script tag inside a section runs every time the section HTML is replaced. If your listener registration is inline, you end up with a new listener added on every edit without the old one removed. The result is duplicate initializations, broken sliders, and in severe cases, a frozen theme editor (every edit triggers N parallel inits for N edits in that session).

Three rules for safe re-initialization:

  1. Store the handler in a named variable so you can pass the same reference to removeEventListener.
  2. Run the unload cleanup in shopify:section:unload, which fires just before the section is replaced.
  3. Scope every DOM query to event.target or document.getElementById('shopify-section-' + event.detail.sectionId), never to document globally.
// sections/my-carousel.liquid, inline <script>
(function () {
  const sectionId = {{ section.id | json }};
  const selector = '.my-carousel__track';

  function initCarousel(container) {
    // Set up your carousel instance, store it on the container
    if (container._carousel) return; // idempotency guard
    container._carousel = new MyCarousel(container);
  }

  function destroyCarousel(container) {
    if (container._carousel) {
      container._carousel.destroy();
      container._carousel = null;
    }
  }

  // --- Initial page load ---
  const initialEl = document.querySelector(
    '#shopify-section-' + sectionId + ' ' + selector
  );
  if (initialEl) initCarousel(initialEl);

  // --- Editor re-initialization ---
  if (Shopify.designMode) {
    function handleLoad(event) {
      if (event.detail.sectionId !== sectionId) return;
      const el = event.target.querySelector(selector);
      if (el) initCarousel(el);
    }

    function handleUnload(event) {
      if (event.detail.sectionId !== sectionId) return;
      const el = document.querySelector(
        '#shopify-section-' + sectionId + ' ' + selector
      );
      if (el) destroyCarousel(el);
      // Remove own listeners so they do not stack
      document.removeEventListener('shopify:section:load', handleLoad);
      document.removeEventListener('shopify:section:unload', handleUnload);
    }

    document.addEventListener('shopify:section:load', handleLoad);
    document.addEventListener('shopify:section:unload', handleUnload);
  }
})();

The IIFE wrapper keeps sectionId and both handler references in the same closure, so removeEventListener can receive the exact same function object. Without this, every edit to the section adds another permanent listener.

Theme editor events available for custom sections

Shopify fires a full set of non-cancellable, bubbling events from the editor. For a carousel or tab component that also needs to respond to block editing:

EventPayloadWhen to use
shopify:section:load{ sectionId }Re-initialize the whole section.
shopify:section:unload{ sectionId }Destroy instances, remove listeners.
shopify:section:select{ sectionId, load }Scroll into view, activate preview state.
shopify:section:deselect{ sectionId }Reset preview state.
shopify:block:select{ sectionId, blockId, load }Jump to the edited slide or tab.
shopify:block:deselect{ sectionId, blockId }Return to default state.
shopify:inspector:activate(none)Theme Inspector overlay turned on.
shopify:inspector:deactivate(none)Theme Inspector overlay turned off.

Verifying the result

Once you have made changes, verify across both axes:

Server-side (Liquid render time):

  • Reload Theme Inspector. Total render time should drop below 200ms on pages with your section. Watch for regression after adding new Liquid logic.

Client-side (LCP and CWV):

  • Use Chrome DevTools Performance panel with CPU 4x slowdown and Fast 3G throttling. Confirm the LCP element (reported in the Performance Insights sidebar) is your hero image, not a fallback text node.
  • Run PageSpeed Insights on the live URL. Field data from CrUX (the "Discover what your real users are experiencing" section) is the number that affects Google ranking, not the lab score.
  • For the editor, open the theme customizer, add your section, edit a setting, and inspect the browser console for duplicate logs or errors. No duplicate carousel inits, no errors on setting changes.

For a worked example of the full audit flow across a large-catalog store, see the case studies section. For definitions of terms like TTFB, CrUX, and fetchpriority, the glossary has concise explanations.

A note on CSS deferral via section.index

The same section.index branch that controls image loading can also defer non-critical CSS. For sections at index 4 or higher, loading the section stylesheet asynchronously (via a media attribute swap trick or a dynamically injected <link>) avoids render-blocking. Shopify's own performance blog documents this pattern alongside the image strategy. It is worth doing for sections that contain large component stylesheets (tabs, accordion, full-bleed video) but are rarely in the initial viewport.

Conclusion

The three problems covered here compound each other in production. A slow Liquid render delays TTFB, which delays the browser's ability to discover the LCP image. If that image is then lazy-loaded, LCP stacks another penalty on top. And if the section's JavaScript never re-initializes cleanly in the editor, development slows down because every test requires a full page reload. Fix them in order: audit with Theme Inspector first, then set the loading strategy with section.index, then harden the editor lifecycle with named listener references and an unload cleanup. Each step is independently verifiable.

If you need this built rather than doing it in house, Lintel, the studio I run, takes on Shopify performance and technical SEO projects like this.

Frequently asked questions

What is the Shopify Theme Inspector and how do I use it?

The Shopify Theme Inspector is an official Chrome extension (version 3.0.2 as of January 2025) that renders a flame graph of server-side Liquid render times. Install it from the Chrome Web Store, sign in with your Shopify credentials, and load any page on your store to see per-file and per-line render costs. Aim for a total render time under 200ms, with 500ms as the hard ceiling.

Why does my custom section break in the Shopify theme editor after I edit a setting?

When a section setting changes, Shopify re-renders the entire section HTML, which removes all previously attached DOM event listeners. You need to listen for the shopify:section:load event and re-run your JavaScript initialization inside it, scoped to the specific section by sectionId. Always clean up listeners in shopify:section:unload to prevent stacking.

What is section.index in Shopify Liquid and how does it affect LCP?

section.index is a 1-based integer that returns the position of a section within its location (template, header, footer, etc.). Use it to apply loading="eager" and fetchpriority="high" to images in the first one or two sections, and loading="lazy" to everything at index 4 or higher. Note that section.index returns nil for static sections hardcoded in theme.liquid rather than included via a JSON template.

Seven years of Shopify, on one page.

Roles, projects, stack and certifications are on the resume.

Resume Download PDF LinkedIn