Writing block markup

Block markup is a Vue 3 template. The cart compiles it in the shopper’s browser, so it has to be a template only: no <script>, no <style> and no imports. Style blocks with Custom CSS in the Code tab instead; see Texts and styles.

Each block is wrapped in a div with the classes ns-cart-block and ns-cart-block-<type>, such as ns-cart-block-items, which you can use in CSS.

Showing data

Curly braces show a value. Anything in them is a JavaScript expression:

<p>You have {{ ns.itemCount }} items, {{ ns.totalFormatted }} in total.</p>

Attributes take values with a colon in front:

<a :href="ns.routes.cart">Go to the cart page</a>

Showing things conditionally

<p v-if="ns.total >= 5000">Your order ships free.</p>
<p v-else>Spend {{ ns.formatMoney(5000 - ns.total) }} more for free shipping.</p>

Lists

<ul>
  <li v-for="item in ns.items" :key="item.key">
    {{ item.quantity }} × {{ item.product_title }}
  </li>
</ul>

Always give list items a :key. For cart lines, use item.key.

Clicks and forms

@click runs an action:

<button type="button" @click="ns.close()">Keep shopping</button>

Some blocks provide form state you can bind with v-model, such as the discount code field. See Block variables.

Settings

config holds the block’s settings. A setting the merchant has never changed may be missing, for example on blocks added before the setting existed, so write conditions that still work without it. For a setting that is on by default, compare with false:

<!-- Cart title bar: "Show cart title" is on unless the merchant turned it off -->
<h2 v-if="config.showCartTitle !== false">{{ t('general.cartTitle') }}</h2>

Block variables lists each block’s settings.

Raw HTML

v-html shows a setting as HTML rather than text. The announcement message uses it so merchants can add links:

<p v-html="config.text"></p>

Only use it for content the merchant wrote, never for anything a shopper typed.

A complete example

A Custom HTML block that thanks shoppers once their cart passes £100, with a button to check out:

<div v-if="ns.total >= 10000" class="thanks">
  <p>Thanks for shopping with us. Your order includes a free gift.</p>
  <button type="button" @click="ns.checkout()">Check out</button>
</div>

What doesn’t work

• Components of your own, plugins and imports. The only components available are Vue’s built-in ones, such as <Transition> and <component>.
• Template refs and lifecycle hooks: there’s no <script> to use them in.
• Globals such as window or document aren’t available inside expressions. JavaScript’s built-ins, such as Math, Number, Date, JSON and Intl, are.