Template reference

How you open the code editor is on Your own code on a component.

Where: the designer, Customize with code › Code on a component, in Advanced mode. The Custom component section follows the same rules.

#The root is the storefront's

Every component has a root that the storefront draws. Your template is the content of the root.

• The header's root is [data-bs-header]. The storefront sets the states [data-bs-transparent], [data-bs-scrolled] and [data-bs-sticky] on the root, even when the header is your own HTML.
• Write no <header> of your own in the template. Start with what goes inside.
• Your CSS is scoped to the root. Your JS gets the root as root.
• A Custom component section has the root [data-bs-block="<section-id>"].

Hooks and CSS reference lists every root.

#Template syntax

The template is HTML with variables in double curly braces. This is the whole syntax.

• Empty text, 0, an empty list and false count as false.
• There is no way to output unescaped HTML.
• There are no helpers and no included templates.

#Limits

• BunStack cuts anything longer and shows a warning that says where, for example css cut at 200 000 characters.
• A render stops after 50 000 steps. A loop inside a loop cannot hang the storefront.
• The designer renders a template of 33 333 characters or more once without data. When that render hits a limit, the limit shows under May cut with some data on the Code tab.
• The storefront lists only what its own render cuts.

#Errors and warnings

A template that cannot be read draws nothing. This applies, for example, to an {{#each}} that is never closed, or a block closed with the wrong tag. The storefront then shows the standard look, and the designer shows the error at the code.

A warning can concern a CSS rule that could not be scoped, or an option that was rejected.

#Variables

#Header, Menu panel and Footer

The three share one set of variables. The Custom component section gets the same set.

#Product card

One template per card. It is drawn for each product in a grid.

#Product page

The gallery and the buy panel, drawn for the variant shown. When the customer chooses another variant with select-variant, the template is drawn again. The price, the SKU, the stock row, product.variantId and every selected update with it. The rest of the page is the standard page's: details, reviews and related products. Under the template the storefront draws the product's questions, the line about cart add-ons and the Optional add-ons box. add-to-cart in the template adds the add-ons the customer ticked and stops at a required question left empty, as the standard button does.

#Gallery

The product images on the product page. When the product page is your own HTML, that template draws the gallery itself, and the gallery's design is not drawn at all. The code editor, the storefront's report and the canvas show this, for example Not rendering — the product page is your own HTML and draws the gallery itself.

#Category

The collection page with the products it lists: a category, All products or search results. The template gets the page's filters as data in filters[]: each group with its values, counts, ticks and a link that ticks or unticks the value. The shop puts no filters into the template's own markup. A template lists what the address says (?sort=…&f.…&category=…). The template replaces the Collection page's sections, the product grid included. The page's own CSS (the Code tab of the Collection page) still applies.

#Banner

The section's own settings.

Write the heading as <h1> when the banner is the page's title block. Then it is the page's title. When the template has no <h1>, the storefront adds a hidden page title after the banner when the banner is the page's title block. The first banner or hero on the page is the title block, unless a heading section at level 1 takes the title.

#Actions

Your markup has no event handlers of its own. Put data-bs-action on an element, and the storefront does the rest on click. The storefront uses the same listeners as for the standard markup. The attribute works on any element, including an <svg>.

• When an attribute that is required is missing, nothing happens on the click.
• data-bs-quantity must be a positive whole number. Anything else reads as 1.
• An action that does not exist, or that lacks a required attribute, gives a warning when the template is compiled. The warning shows at the code and as <!-- bs-component-warning: … --> in the storefront's HTML.
• subscribe-newsletter needs a form with data-bs-newsletter and a field name="email". It runs when the form is submitted, so Enter in the field works. The address gets the same check and the same reply as in the standard footer.

add-to-cart without data-bs-variant-id, for example on a card, asks the storefront about the product:

#Hooks

The hooks are the attributes in the storefront's HTML that your CSS and JS target: the component's root, inner elements and states on the root. Every hook per component, the hooks on the page and the rules in the tokens CSS are under Hooks and CSS reference.

#Sanitising

BunStack sanitises the rendered template before it reaches the page, the same way on the server and in the browser.

Attributes kept:

• on every element: class, id, title, role, tabindex, lang, dir, hidden, style, translate, every aria-*, every data-bs-* and data-footer-*
• on links: href, target, rel
• on images: src, srcset, sizes, alt, width, height, loading
• on buttons and fields: type, name, value, placeholder, disabled
• on form: action when it is a path in the storefront, for example /search, and method when it is get or post
• on SVG: viewBox, fill, stroke, stroke-width, d, points and the other drawing attributes

BunStack removes:

• script, style, iframe, object, embed, noscript, template, textarea, select, video, audio, canvas, dialog, math and title, with all their content
• every on* attribute and every comment
• data-* other than data-bs-* and data-footer-*
• addresses that are not relative, https:, http:, mailto: or tel:, except data: images on img
• an action that points outside the storefront

BunStack removes an element that is not in the list but keeps its content. It sanitises style="…" like other CSS. On links it keeps target="_blank" and adds rel="noopener", and it keeps target="_self". It removes other target values. It closes open elements at the end, so the result is always balanced HTML.

#Classes and sizes

The standard markup has a few Tailwind classes, for example flex, items-center and gap-4. The designer compiles no new classes from your template. A class that is not already in the storefront does nothing. Set size and spacing on the Design tab, in Code › CSS on the hooks or as style on the element.

#CSS

The CSS on the Code tab applies to the component only. How the selectors are scoped to the root, what sanitising removes and how to load your own fonts are under Hooks and CSS reference.

About px and rem: see Your own CSS and head code.

#JS

• The JS runs once per page load, when the page has loaded, on every page where the component is.
• It gets the component's root element as root. When the component is not on the page, it does not run.
• The menu panel's root exists only while the panel is open. Its JS runs every time the panel opens, against the new root. Bind listeners on root, not on document.
• An error, a syntax error included, goes to the browser console with the style's name. It stops neither the page nor other components' JS.
• The code also runs on the canvas. Turn off Run JS in the builder to pause it there for the session. The storefront and Preview (⌘P) still run it.

root.querySelectorAll('[data-bs-header-icons] a').forEach((a) => {
  a.addEventListener('mouseenter', () => a.classList.add('is-hot'));
});

A product card is on a page many times. root is then the first card. Use document.querySelectorAll('[data-bs-card]') for all of them.

The page's JS on the Code tab runs the same way, without root. What you write on the Collection page applies to every category page.

#Example: a navbar on a Classic storefront

The goal is a full-width header. It is transparent over the hero image with a white logo and white icons, and white once the page has scrolled 24 px. On the right are four icons of 30 px: search, wishlist, cart and menu. Most of it is controls. The rest is six lines of CSS.

The controls on the component panel for Header:

1. Replace the home page's text hero with an Image banner with Width full and a dark photo.
2. Choose Look: Icons + panel.
3. Set Options: Sticky on, Transparent over hero on, Menu label off, Search on, Cart on, Announcement bar off.
4. Choose the black logo as Logo under Content, with height 40. Choose the white one as Light logo.
5. Check that Theme › Colours › Header text over hero is white.

Turn on Advanced, press Customize with code and write under Code › CSS:

[data-bs-header] { padding: 16px; }
@media (min-width: 768px) { [data-bs-header] { padding: 32px; } }
[data-bs-header-inner] { max-width: none; }
[data-bs-header-icons] { gap: 16px; }
[data-bs-header-icons] a, [data-bs-header-icons] button { opacity: 1; }
[data-bs-header-icons] svg { width: 30px; height: 30px; stroke-width: 1.6; }

Press Save as new style and name the style "My navbar". The style is now under Your header styles in every storefront of the workspace. The logos belong to the theme. Set them under Content in each storefront.

#The same navbar as your own HTML

Open Code › HTML and press Start from the standard markup. The field fills with the standard look's markup. The template below is the same navbar written by hand. It uses the same inner hooks, so the CSS above applies unchanged. The burger opens the storefront's standard panel, which has its own Close button and closes with Escape.

<div data-bs-header-inner>
  <a href="/" aria-label="{{storefront.name}}">
    <img src="{{brand.logoUrl}}" alt="{{storefront.name}}" height="{{brand.logoHeight}}" class="logo-dark">
    <img src="{{brand.footerLogoUrl}}" alt="" height="{{brand.logoHeight}}" class="logo-light">
  </a>
  <div data-bs-header-icons>
    <button type="button" data-bs-action="open-search" aria-label="{{i18n.search}}">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/></svg>
    </button>
    <a href="/wishlist" data-bs-wishlist-icon aria-label="{{i18n.wishlist}}">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.7l-1-1.1a5.5 5.5 0 0 0-7.8 7.8L12 21l8.8-8.6a5.5 5.5 0 0 0 0-7.8z"/></svg>
    </a>
    <button type="button" data-bs-action="open-cart" data-bs-cart-icon aria-label="{{i18n.cart}}">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><path d="M6 6h15l-1.5 9h-12z"/><circle cx="9" cy="20" r="1"/><circle cx="18" cy="20" r="1"/><path d="M6 6 5 3H2"/></svg>
      <span data-bs-cart-count>{{cart.count}}</span>
    </button>
    <button type="button" data-bs-action="open-menu" data-bs-menu-button aria-label="{{i18n.menu}}">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true"><path d="M3 6h18M3 12h18M3 18h18"/></svg>
    </button>
  </div>
</div>

In the standard markup the storefront swaps the logo itself. In your own template both images are in the markup, and the CSS chooses with the state on the root:

[data-bs-header-inner] { display: flex; align-items: center; justify-content: space-between; }
[data-bs-header-icons] { display: flex; align-items: center; }
.logo-light { display: none; }
[data-bs-transparent]:not([data-bs-scrolled]) .logo-dark { display: none; }
[data-bs-transparent]:not([data-bs-scrolled]) .logo-light { display: inline; }

#The menu panel as your own HTML

The storefront draws the panel's root [data-bs-menu] and opens it with open-menu. The template loops the menu's links from Menu panel › Links, the big ones with their subcategories and then the small ones:

<nav aria-label="{{i18n.menu}}">
  <ul>
    {{#each menu.links}}
    <li>
      <a href="{{this.href}}">{{this.label}}</a>
      {{#if this.children}}
      <ul>{{#each this.children}}<li><a href="{{this.href}}">{{this.label}}</a></li>{{/each}}</ul>
      {{/if}}
    </li>
    {{/each}}
    {{#each menu.secondary}}<li><a href="{{this.href}}">{{this.label}}</a></li>{{/each}}
  </ul>
  {{#if contact.email}}<p data-bs-menu-contact><a href="mailto:{{contact.email}}">{{contact.email}}</a></p>{{/if}}
  <button type="button" data-bs-action="close-menu">{{i18n.close}}</button>
</nav>

open-search opens the storefront's search box as a layer above the header and the panel. When your markup has an element with [data-bs-search-slot], the storefront draws the search box there instead. A search form of your own also works:

<form action="/search" method="get" role="search">
  <input type="search" name="q" placeholder="{{i18n.searchPlaceholder}}" aria-label="{{i18n.search}}">
  <button type="submit">{{i18n.search}}</button>
</form>

#A product card as your own HTML

The storefront draws the card's root [data-bs-card]. The template is the inside. The button gets its product through the attributes.

<a href="{{product.href}}">
  <div data-bs-card-media>
    {{#if product.image}}<img src="{{product.image}}" alt="{{product.imageAlt}}" loading="lazy">{{/if}}
    {{#if product.badge}}<span class="badge">{{product.badge}}</span>{{/if}}
  </div>
  <div data-bs-card-body>
    <h3 data-bs-card-title>{{product.title}}</h3>
    <p data-bs-card-price>{{#if product.compareAtPrice}}<s>{{product.compareAtPrice}}</s> {{/if}}{{product.price}}</p>
  </div>
</a>
<button type="button" data-bs-action="add-to-cart" data-bs-product-id="{{product.id}}">Add to cart</button>