Section rendering API​

Use the section rendering API to fetch HTML for theme sections through AJAX requests. This enables you to update page content dynamically by obtaining and replacing specific elements without reloading the entire page.

For example, you can implement pagination for research results using the section rendering API, allowing for page changes without a full page reload when switching between pages.

Request sections​

You can use the sections query parameter to render specific page sections. The values of sections are unique IDs to identify sections. Refer to Obtain section IDs for how to get values of sections.

Separate the section ID values by commas, as shown in the following example:

?sections=sections--header-group__announcement-bar,sections--header-group__header

You can render sections on any page context by appending the sections parameter to any page URL. For example, if you make a request to the homepage using /?sections=sections--header-group__header, it will return the HTML fragment of the corresponding section to populate the page.

The response for the API is a JSON object, including the IDs and HTML files for each section. Refer to Example for a response sample.

Example​

The following code sample requests two sections using the JavaScript fetch method:

fetch('/?sections=sections--header-group__announcement-bar,sections--header-group__header').then((response) => {
  const renderSections = response.json();
  const announcementBarHtml = renderSections['sections--header-group__announcement-bar'];
  const headerHtml = renderSections['sections--header-group__header'];
})

The response is as follows:

{
  "sections--header-group__announcement-bar": "<div id=\"shopline-section-sections--header-group__announcement-bar\" class=\"section\">\n<!-- section content -->\n</div>",
  "sections--header-group__header": "<div id=\"shopline-section-sections--header-group__header\" class=\"section\">\n<!-- section content -->\n</div>"
}

Error codes​

Sections that fail to be rendered, such as due to non-existent themes, will return null in the JSON response. The response may have an HTTP 200 status code, but still contain one or more sections with null values. Be prepared to handle situations when null values are returned.

Request a single section​

If you want to render a single section, you can use the section_id and sections query parameters to request the section. However, it is highly recommended that you use section_id to request a section.

?section_id=sections--header-group__announcement-bar

Similar to sections, you can use section_id to render a single section at any context on a page. If you use the section_id parameter to request a section, HTML for the section is returned.

<div id=\"shopline-section-sections--header-group__announcement-bar\" class=\"section\">\n<!-- section content -->\n</div>

Obtain section IDs​

You can obtain section IDs in the following ways:

• Sline section object: Use section.id.
• Extract section IDs from ID attributes in a section's HTML.

Extract section IDs from ID attributes

<div id="shopline-section-[section-id]" class="shopline-section">
  <!-- section content -->
</div>

If you add a new section to the JSON template, a unique ID is generated for the section. For example, if two product list sections are added to the same page, each will have a unique ID. This allows you to identify and work with each section easily.