Liquid Section Renderer

A Web Component that utilizes Shopify's Section Rendering API to dynamically render Shopify sections via AJAX requests. For those that are newer to the Section Rendering API, when should you consider using it? There are two most common scenarios that often overlap that include the following:

• To avoid redundant logic between Liquid and JavaScript (eg. product price display)
• Some data is easier accessible in Liquid with linked objects such as products and variants

Browser Support

This component works in all modern browsers. For older browser support, include the following polyfills:

• Custom Elements: Include @webcomponents/custom-elements
• URL/URLSearchParams: Include url-polyfill for IE11 support

Installation

NPM

See the following NPM page for more information.

npm install liquid-section-renderer
yarn add liquid-section-renderer

To import into your project:

import 'liquid-section-renderer';

Manual

Copy the contents of liquid-section-renderer/dist/liquid-section-renderer.min.js into your project into the assets/liquid-section-renderer.js directory. Then include the JS file into your theme as follows:

<script src="{{ 'liquid-section-renderer.js' | asset_url }}" defer></script>

Examples

Basic Usage

In the below example, this component finds the closest parent with the class shopify-section and replaces the section, including the <liquid-section-renderer> element. It also infers that to use the current page's pathname to fetch content from. If you wish to be more specific in what is replaced, then see the following examples.

<section id="shopify-section-template--12345678909876__main" class="shopify-section section">
  <!-- Section content before : copy from here -->
  <liquid-section-renderer>
    <button trigger>
      Click to replace Shopify section
    </button>
  </liquid-section-renderer>

  <!-- Section content after : copy to here -->
</section>

Render Specific URL

In the below example, this component will make a request to the specified URL using the render-url attribute. As well as specifying which section file (eg. sections/main-product) to get the data from, and where in the DOM to replace the content using the destination attribute. This is useful if you want to get specific content such as product data from a single product.

<liquid-section-renderer
  render-url="/products/example-product?variant=10101010"
>
  <button
    trigger
    section="main-product"
    destination="#product-content"
  >
    Update Product
  </button>

  <div id="product-content">
    <!-- Content replaced here -->
  </div>
</liquid-section-renderer>

Multiple Destination Updates

This example is similar to the last, but the updates attribute replaces the section and destination attributes. This allows you to fetch content from a single URL while fetching multiple sections and updating multiple destinations, each mapped individually. This is useful in scenarios such as using a variant selector to update price and badges separately, when updating the entire section would break events or other functionality.

<liquid-section-renderer
  render-url="/products/example-product?variant=10101010"
>
  <button
    trigger
    updates='[
      {"section": "product-info", "destination": "#product-info"},
      {"section": "product-recommendations", "destination": "#recommendations"}
    ]'
    update-mode="replace"
  >
    Update Multiple
  </button>

  <div id="product-info">
    <!-- Content replaced here -->
  </div>

  <div id="recommendations">
    <!-- Content replaced here -->
  </div>
</liquid-section-renderer>

Trigger on Page Initialization

In the following example, the component will trigger on page initialization. This is useful in scenarios such as using Shopify's Product Recommendations API. In this instance we would be looking for a section file named sections/render-product-recommendation, and the destination would be the trigger element itself.

<liquid-section-renderer
  render-url="{{ routes.product_recommendations_url }}?product_id={{ product.id }}&limit=4&intent=related"
>
  <div
    trigger-init
    section="render-product-recommendation"
    destination="[data-product-recommendations]"
    data-product-recommendations
  >
    <!-- Content will be rendered here -->
  </div>
</liquid-section-renderer>

Trigger with Intersection Observer

We can easily replace trigger-init with trigger-intersect to trigger the section update when the element becomes visible in the viewport. We can also use the intersect-margin attribute to specify in pixels how closer the element needs to be to the viewport to trigger the section update.

<liquid-section-renderer
  render-url="{{ routes.product_recommendations_url }}?product_id={{ product.id }}&limit=4&intent=related"
  intersect-margin="200"
>
  <div
    trigger-intersect
    section="render-product-recommendation"
    destination="[data-product-recommendations]"
    data-product-recommendations
  >
    <!-- Content will be rendered here -->
  </div>
</liquid-section-renderer>

Multiple Render URLS

In the following example demonstrates how the render-url can be set on the trigger element, allowing for interactions such as paginated collection pages where multiple URLs are needed.

<liquid-section-renderer>
  <button
    trigger
    render-url="{{ paginate_prev_url }}"
  >
    Load previous products
  </button>

  <!-- Products grid here -->

  <button
    trigger
    render-url="{{ paginate_next_url }}"
  >
    Load next products
  </button>
</liquid-section-renderer>

Dynamic Attribute Updates

The following examples demonstrates how the its possible to dynamically update attributes such as the render-url such as to use it with search. This example utilizes Alpine JS for the dynamic input data.

<liquid-section-renderer
  id="Search"
  x-data="{ query: '' }"
  :render-url="`{{ routes.predictive_search_url }}?q=${query}&resources[type]=product`"
  loading-selector="#searchInput"
  loading-class="opacity-50"
>
  <div class="max-w-screen-xl mx-auto flex flex-col items-center justify-center gap-4 py-6">
    <h3>Predictive Search</h3>

    <input
      name="q"
      id="searchInput"
      x-model="query"
      class="border rounded py-2 px-6 transition-[opacity,color]"
      placeholder="Search: product name"
      section="render-predictive-search"
      destination="#searchResult"
      update-mode="replace"
      trigger
    />

    <div id="searchResult" x-show="query.length > 0"></div>
  </div>
</liquid-section-renderer>

Parent Attributes

Attribute	Type	Default	Description
debounce	Integer	300	The time to wait in milliseconds before sending request after a trigger event.
history-mode	String	replace	Controls URL history behavior. Accepts add/push, or replace.
intersect-margin	Integer	0	Margin in pixels around the viewport for intersection observer triggers. Helps with lazy loading sections that are close to the viewport.
intersect-threshold	Integer	10	Percentage (1-100) of element that needs to be visible to trigger intersection observer.
id	String	random	A unique identifier for the component.
loading-selector	String	none	Uses querySelector to find the loading element. If not set, no loading indicator will be shown.
loading-class	String	none	Class to add to loading element while loading. If unset and a loading-selector is provided, the component will inline display: none.
render-url	String	location.pathname	Specify the URL to request the section from.
scoped	Boolean	true	If set false, querySelector is scoped the entire document, otherwise is scoped to the component.
timeout	Integer	5000	The time to wait for a response in milliseconds before cancelling the request.
update-url	String	none	Update the URL after section is updated.
update-title	String	none	Update the page title if updating page URL.

Trigger Attributes

Attribute	Type	Default	Description
destination	String	none	Uses querySelector for the element to update with new section content.
query	String	none	Uses querySelector to find element within section. If not found, uses entire section.
section	String	none	The file name reference of the section to render found in sections/<file-name>.liquid.
trigger	Boolean	none	Determines which element triggers a section update.
trigger-init	Boolean	none	Immediately runs at end of component initialization.
trigger-intersect	Boolean	none	Triggers when element becomes visible in viewport based on intersection observer settings.
intersect-once	Boolean	true	Controls whether the intersection observer trigger fires only once or every time it is intersecting.
render-url	String	none	Override the parent component's render-url for this specific trigger.
update-mode	String	replace	How the new section content is inserted. Accepts replace, append/after, or prepend/before.
updates	Array	none	Array of section/destination pairs for updating multiple sections.

Updates Array

The following are the included attributes within the updates array.

<button
  updates='[
    {
     "destination": "#SectionId",
     "section": "section-file-name",
     "updateMode": "replace",
     "query": "[data-items]"
    }
  ]'
>
  Trigger
</button>

Event Listeners

The component automatically binds appropriate events based on the trigger element as follows. To note, all events have event.preventDefault() applied to avoid unintended actions or form submissions.

Element Type	Event
button	click
form	submit
input	input
select	change
textarea	input
*	click

Window Events

The component dispatches the following events during the section rendering lifecycle. A randomly generated id is included in the detail object to differentiate events.

Event Name	Description
liquid-render-init	Fired when the component is initialized
liquid-render-destroying	Fired at beginning of the component being destroyed
liquid-render-started	Fired when a section render request begins
liquid-render-ended	Fired after a section render request ends
liquid-render-error	Fired when a section render request fails

Error Handling

The component includes built-in error handling for the following scenarios:

• If neither updates array nor both section and destination attributes are provided, it will infer the current section it is within
• If the provided updates array structure is invalid, an error will be thrown
• If a section render request fails or times out, a liquid-render-error event will be dispatched

Hiding Loading Selector on Page Load

If you have are not using classes to hide/show your loading element and wish for the component to hide it using inline display: none, you can use the cloak attribute to hide the loading element, before the component is initialized. Once the component is initialized, the cloak attribute will be removed from the loading element.

Apply the following CSS to your main stylesheet:

[cloak] {
  display: none;
}

Add the attribute on your loading element as follows:

<liquid-section-renderer
  loading-selector="#loading"
>
  <!-- Your content -->
  <div id="loading" cloak>Loading...</div>
</liquid-section-renderer>