widget

Renders a widget template directly by its folder name. Unlike {% template %} which renders all widgets from the database, {% widget %} renders a specific widget file from disk.

Usage

{% widget "hero-banner" %}

Resolves to widgets/hero-banner/widget.njk and renders it with the current page context.

With Data

Pass extra data via keyword arguments:

{% widget "product-card", columns=4, show_price=true %}

Inside the widget template, access the data via widget.data or widget.settings:

<div class="grid-{{ widget.data.columns }}">
  {% if widget.settings.show_price %}
    <span>{{ product.pricing.price | money }}</span>
  {% endif %}
</div>

Available Context

The widget template has access to:

Variable	Source
products, collection, store, ...	Page context (same as the parent page)
widget.type	The widget key (e.g. "product-card")
widget.data	Keyword arguments passed to the tag
widget.settings	Same as widget.data
widget.blocks	Always []
widget.id	Always null

Section Rendering

Combine with data-qumra-section to enable server-side rerendering without page reload:

<div data-qumra-section="products-grid">
  {% widget "products-grid" %}
</div>

When filters change, the SDK automatically fetches fresh HTML from the server and swaps the content. See Filters Module for details.

Recursion Protection

If a widget template calls itself (directly or indirectly), the recursive call is silently skipped to prevent infinite loops.

{# widgets/card/widget.njk #}
<div class="card">
  {% widget "card" %}  {# Skipped — returns empty #}
</div>