Tag Reference

Template tags enable theme developers to include and extend templates and blocks, add logical operators, query and filter data, and much more. See all available template tags below.

app_asset_url

The app_asset_url tag is used to reference asset files included in app snippets.

app_asset_url

<script src=="{% app_asset_url 'assets/my-app.js' %}"></script>

The app_hook tag specifies a theme storefront location Apps can inject snippets into to extend storefront templates from Apps. Theme developers should ensure their templates include all available app_hooks to ensure compatibility with all Apps.

app_hook

{% app_hook 'global_header' %}

Available app_hook locations include:

App Hook Location	Description
`global_header`	Used for adding javascript and styles globally to the header of a theme. Should be loaded globally in the header, most likely in `layout/base.html`.
`global_footer`	Used for adding javascript globally to the footer of a theme. Should be loaded globally in the footer, most likely in `layout/base.html`.

add_query_param

The add_query_param tag appends or updates a query parameter on the current URL. Commonly used for building pagination links and filter URLs while preserving existing query parameters.

add_query_param

{% add_query_param request 'page' page_obj.next_page_number %}

Example Pagination with add_query_param

{% if paginator.num_pages > 1 %}
<nav aria-label="pagination">
    <ul class="pagination">
        {% with ''|center:paginator.num_pages as range %}
            {% for _ in range %}
                <li class="page-item {% if forloop.counter == page_obj.number %}active{% endif %}">
                    <a class="page-link" href="{% add_query_param request 'page' forloop.counter %}">
                        {{ forloop.counter }}
                    </a>
                </li>
            {% endfor %}
        {% endwith %}
    </ul>
</nav>
{% endif %}

Argument	Description
request	The current `request` context object.
param_name	The query parameter name to set, eg `'page'`.
value	The value to assign to the parameter.

annotate_form_field

The annotate_form_field tag adds HTML attributes to a form field based on its Django form field properties (required, type, etc.). Useful for adding client-side validation and accessibility attributes.

annotate_form_field

{% annotate_form_field field %}
{{ field }}

boolean operators

If tags may be used in combination with boolean operators for conditional control flow.

Operator	Description
`and`	multiple conditions are true
`or`	either condition is true
`not`	a condition is not true
`in`	contained within
`not in`	a condition is not true
`is`	two values are the same
`is not`	two values are not the same
`==`	equality
`!=`	inequality
`<`	less than
`>`	greater than
`<=`	less than or equal to
`>=`	greater than or equal to

cart_form

The cart_form tag generates an add-to-cart form for a product. Required on every product page to enable purchasing.

cart_form

{% cart_form request product 'single' as cart_form %}

Example Product Add to Cart Form

{% cart_form request product 'single' as cart_form %}
<form method="post" action="{% url 'cart:add' product.slug %}">
    {% csrf_token %}
    {{ cart_form }}
    <button type="submit" class="btn btn-primary">
        Add to Cart
    </button>
</form>

Argument	Description
request	The current `request` context object.
product	The `product` context object.
form_type	The form type, typically `'single'`.
variable	Assigned template variable name for the form.

comment

Ignores everything between {% comment %} and {% endcomment %}. An optional note may be inserted in the first tag. For example, this is useful when commenting out code for documenting why the code was disabled.

comment

<p>Rendered text with {{ pub_date|date:"c" }}</p>
{% comment "Optional note" %}
    <p>Commented out text with {{ create_date|date:"c" }}</p>
{% endcomment %}

core_js

The core_js tag outputs the platform's core JavaScript bundle. This is required in every theme's base layout and powers cart functionality, AJAX form submissions, CSRF token handling, and other platform features.

core_js

{% core_js %}

Example Placement in Base Layout

    {# jQuery must be loaded before core_js #}
    <script src="{{ 'jquery.min.js'|asset_url }}"></script>
    {% core_js %}
    <script src="{{ 'main.js'|asset_url }}"></script>
</body>
</html>

jQuery must be loaded before {% core_js %}. The platform's core JavaScript depends on jQuery being available in the global scope.

csrf_token

This tag is used for CSRF protection and required on any template with a form that sends a POST request to the back end.

csrf_token

<form>
    {% csrf_token %}
    <input type="text" id="example" name="Example Input">
    <input type="submit" value="Submit">
</form>

extends & block

Extends and block tags allow you to define blocks of content in a base template that can be overridden by templates that extend from it for template inheritance.

layouts/base.html

<!DOCTYPE html>
<html lang="en">
<head>
    <link rel="stylesheet" href="{{ 'assets/style.css'|asset_url }}">
    <title>{% block title %}My amazing store{% endblock %}</title>
</head>

<body>
    <div id="sidebar">
        {% block sidebar %}
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
        {% endblock %}
    </div>

    <div id="content">
        {% block content %}{% endblock %}
    </div>
</body>
</html>

templates/blog.html

{% extends "layouts/base.html" %}
{% block title %}My Blog Post Title{% endblock %}
{% block sidebar %}
    <div class="sidebar">
        <h4>Custom Sidebar</h4>
    </div>
{% endblock %}
{% block content %}
    <h4>My Blog Post Title...</h4>
{% endblock %}

for

Loops over each item in array, making the item available in a context variable. For example, to display a list of products provided in the {{ products }} variable.

for

<ul>
    {% for each in products %}
    <li>{{ each.get_title }} - Rating {{ each.rating }} stars</li>
    {% endfor %}
</ul>

if, elif, & else

Use the if tag to evaluate if a variable is "true" and control the contents displayed.

if, elif, & else

{% if products_list > 2 %}
    <p>Number of products: {{ products_list|length }}</p>
{% elif products_list %}
    <p>We only have a single product now.</p>
{% else %}
    <p>Sorry, there are no products.</p>
{% endif %}

include

Loads a template and renders it with the current context. This is a way of including other templates within a template.

include

<html lang="en">
<body>
    {% include "partials/footer.html" %}
</body>
</html>

A word of caution, multi-level inclusion inside of iterative loops can create performance penalties while rendering a page html for site visitors. Use includes sparingly when working inside iterative loops.

image_thumbnail

The image_thumbnail tag is used to resize images dynamically in templates. The tag accepts arguments that control how the image is resized.

image_thumbnail

{% with image=line.product.primary_image %}
      {% image_thumbnail image.original "200x200" upscale=False as thumb %}
      <a href="{{ line.product.get_absolute_url }}">
         <img class="thumbnail" src="{{ thumb.url }}" alt="{{ product.get_title }}">
      </a>
{% endwith %}

Argument	Description
size	Example, 100x100 (widthxheight), sets the desired image size in pixels. If width and height are given the image is rescaled to maximum values of height and width given. Aspect ratio preserved.
crop	This option is only used if both width and height is given. Crop behaves much like css background-position. The image is first rescaled to minimum values of height and width given, this will be equivalent to the padding box in the above text.
upscale	Upscale is a boolean and controls if the image can be upscaled or not. For example if your source is 100x100 and you request a thumbnail of size 200x200 and upscale is False this will return a thumbnail of size 100x100. If upscale was True this would result in a thumbnail size 200x200 (upscaled). The default value is `True`.
quality	Quality is a value between 0-100 and controls the thumbnail write quality. Default value is `95`.
progressive	This controls whether to save jpeg thumbnails as progressive jpegs. Default value is `True`.
orientation	This controls whether to orientate the resulting thumbnail with respect to the source EXIF tags for orientation. Default value is `True`.
format	This controls the write format and thumbnail extension. Formats supported by the shipped engines are 'JPEG' and 'PNG'. Default value is `JPEG`.
padding	Padding is a boolean and controls if the image should be padded to fit the specified geometry.

now

Displays the current date and/or time, using a format according to the given string. See available date reference for format options.

purchase_info_for_product

The purchase_info_for_product tag is used to retrieve the price of a product in the current user session's currency.

purchase_info_for_product

{% purchase_info_for_product request product as session %}
{% if session.price.exists %}
    {{ session.price.price|currency:session.price.currency }}
{% else %}

Argument	Description
request	Must pass the current `request` context object.
product	Must pass the current `product` context object.

purchase_info_for_line

The purchase_info_for_line tag retrieves the price and availability of a cart line item in the current session's currency. Works the same as purchase_info_for_product but accepts a cart line object.

purchase_info_for_line

{% purchase_info_for_line request line as session %}
{% if session.price.exists %}
    {{ session.price.price|currency:session.price.currency }}
{% endif %}

Argument	Description
request	Must pass the current `request` context object.
line	Must pass a cart `line` context object.

render_field

The render_field tag renders a form field with additional HTML attributes. Use it to add CSS classes, placeholders, and other attributes to Django form fields in templates.

render_field

{% render_field field class+="form-control" placeholder="Enter your email" %}

Example Form with render_field

<form method="post">
    {% csrf_token %}
    <div class="mb-3">
        <label for="{{ field.id_for_label }}">{{ field.label }}</label>
        {% render_field field class+="form-control" %}
        {% if field.errors %}
            <div class="invalid-feedback d-block">{{ field.errors.0 }}</div>
        {% endif %}
    </div>
</form>

Argument	Description
field	The form field object to render.
attributes	HTML attributes to add, using `attr="value"` or `attr+="value"` (append) syntax.

seo

The seo tag generates SEO meta data for products in standardized format for consumption by 3rd party systems.

seo

{% seo %}

The tag is expected to be added to the top of product details template to generate necessary SEO meta data.

t

The t (translation) tag is used to display localized content from a theme's translations files. The t tag accepts a key and additional replacement variable arguments to access the theme translations and return the language appropriate string for display to the user.

{% t 'customer.orders.order_count' with count=orders.count %}

url

Returns an absolute url path reference matching a given view with parameters. See the URL & Template Path reference for a list of all URL names to use with the {% url %} template tag.

url

<a href="{% url 'blog:blog-list' %}">Blog</a>

where

Queries and filters store objects to dynamically assign objects to a variable.

where

{% where {{ objects }} '{{ field_name }}' '{{ lookup_expr }}' '{{ filter_query }}' as {{ variable }} %}

Argument	Description
objects	The global context object. Supported objects include; `products`, `product_categories`, `posts`, `post_categories`, `currencies`, `storefront_geos`
field_name	Object field name to perform the lookup on.
lookup_expr	Query lookup expression; `exact` or `contains`.
filter_query	Your custom query filter.
variable	Assigned template variable name, ie `featured_products`.

Example Usage


{% where products 'title' 'contains' 'watch' as watches %}

<ul>
{% for each in watches %}
    <li><a href="{{ each.get_absolute_url }}">{{ each.title }}</a></li>
{% endfor %}
</ul>

On this page