Section Rendering API
You can use the Section Rendering API to request the HTML markup for theme sections using an AJAX request. This can allow you to update page content without reloading the entire page by fetching and dynamically replacing only certain elements.
For example, you can use the Section Rendering API to paginate search results without performing a full page reload between pages.
Request sectionsAnchor link to section titled "Request sections"
You can use the
sections query parameter to render up to five sections, identified by their section IDs. The response is a JSON object that includes pairs for each section ID and its corresponding rendered HTML.
sections parameter can be a comma-separated list of IDs or an array:
Sections can be rendered in the context of any page by appending the
sections parameter to any page URL. For example, you can request
/?sections=sections--1234__header for the root page, or you can request
/collections/featured?sections=sections--1234__header for a featured collection page.
Sections error responseAnchor link to section titled "Sections error response"
Sections that fail to render, including those that fail because they do not exist for the published theme, are returned as
null in the JSON response. A response might have an HTTP 200 status, but still include one or more sections that failed to render. Because of this, you should account for the possibility of
Request a single sectionAnchor link to section titled "Request a single section"
You can use the
sections parameter and its JSON response in most cases, including rendering a single section. As an alternative, you can use the
section_id query parameter to request a single section.
Sections rendered in response to the
section_id query parameter are returned directly as HTML and, like
sections, this parameter can be used to render a section in the context of any page.
Single section error responseAnchor link to section titled "Single section error response"
If the requested section ID doesn’t exist on the theme, then the server responds with a
Find section IDsAnchor link to section titled "Find section IDs"
You can access a section ID in two ways:
- Through the Liquid
- Extract it from the ID attribute of the section wrapper
Extract a section ID from the wrapperAnchor link to section titled "Extract a section ID from the wrapper"
You can extract a section ID from the ID attribute of the section wrapper. For example, the following is the general format for a section wrapper:
If a section is included in a JSON template or a section group, then it's assigned a dynamic section ID. Dynamic section IDs ensure no two sections of the same type have the same ID.
For example, a section inside of a section group might have an ID of
sections--1234__header, and a section inside of a JSON template might have an ID of
Locale-aware URLsAnchor link to section titled "Locale-aware URLs"
Stores can have dynamic URLs generated for them when they sell internationally or in multiple languages. When using the Section Rendering API, it’s important to use dynamic, locale-aware URLs so that you can give visitors a consistent experience for the language and country that they’ve chosen.
The global value
Alternatively, a section can be loaded in the context of the current page by using
window.location.pathname as a base: