Liquid - Tags: render / include

render

The render tag renders a partial from app/views/partials/. The partial path must be a hardcoded string literal — you cannot use a variable for the path.

{% render 'shared/header' %}
{% render 'user/card', name: user.name, avatar: user.avatar %}

Passing parameters

Pass any number of named key-value pairs:

{% render 'product/card', title: product.title, price: product.price, featured: true %}

Inside product/card.liquid, only the explicitly passed variables (title, price, featured) are available — render creates an isolated scope. Variables from the calling template are not accessible unless passed explicitly.

Isolated scope

Unlike include, render operates in a fully isolated scope:

• Variables from the calling template are not accessible inside the partial.
• Variables defined inside the partial are not accessible in the calling template.
• You must pass every value the partial needs as an argument.

This makes partials self-contained and easier to reason about.

break behaviour

A {% break %} tag inside a rendered partial stops execution of that partial only. Execution of the calling template resumes after the {% render %} call:

{% render 'might-break' %}
This line still executes even if 'might-break' uses {% break %}

with syntax

Pass a single value using the with keyword. The value is available inside the partial under a variable named after the partial:

{% render 'product/card' with product %}

This makes product available as card inside the partial (the variable name matches the partial filename).

---

include

The include tag renders a partial in the caller's scope. Prefer render for self-contained partials; use include when the partial needs access to the calling template's variables or must affect its control flow — for example helpers that redirect or set the response status of the including page, such as the can_do_or_* guards in pos-module-user.

Key differences from render

Feature	render	include
Partial path	Must be a hardcoded string literal	Can be a variable ({% include var %})
Scope	Isolated — only explicitly passed params are accessible	Shared — all calling template variables are accessible
{% break %}	Stops the partial only; calling template continues	Stops the entire render flow

Basic usage

{% include 'mypartial' %}
<br/>
{% include 'mypartial2' %}

You can also include using a variable path:

{% assign partial_name = 'shared/header' %}
{% include partial_name %}

Passing parameters to a partial

{% assign makers = 'subaru,honda,toyota,suzuki,lexus' | split: ',' %}
{% include 'car', minYear: 2000, transmission: 'auto', makers: makers %}

Inside car.liquid:

{{ minYear }} => 2000
{{ transmission }} => auto
{{ makers }} => ["subaru","honda","toyota","suzuki","lexus"]

Local variable using with

If a partial has the same name as a variable you want to pass, use with:

{% parse_json cars %}
[{
  "maker": "Honda",
  "model": "CRX"
}]
{% endparse_json %}
{% include 'car' with cars[0] %}

This creates a variable called car with the value of cars[0] inside the partial.

Iterating over a collection using for

{% parse_json cars %}
[{
  "maker": "Honda",
  "model": "CRX"
}, {
  "maker": "Subaru",
  "model": "Forester"
}, {
  "maker": "Lexus",
  "model": "LFA"
}]
{% endparse_json %}

{% include 'product' for cars %}

This renders the partial for each item. Each iteration has the product variable populated with the current item.

Private variables and exporting them

When you define a variable in a partial, it is not visible in the page that included it (variables flow from top to bottom, not bottom to top).

To use a variable defined inside a partial from outside, use the export tag and context.exports.

app/views/partials/export.liquid

{% parse_json honda %}
{
  "maker": "Honda",
  "model": "CRX",
  "year": "1991"
}
{% endparse_json %}
{% export honda, namespace: "my_car" %}

app/views/pages/include.liquid

{% include 'export' %}
Car: {{ context.exports.my_car }}
My car maker: {{ context.exports.my_car.honda.maker }}

Output:

Car: {"honda"=>{"maker"=>"Honda", "model"=>"CRX", "year"=>"1991"}}
My car maker: Honda