Blocks reference

Blocks are web components you can drop into a report's HTML/Liquid template. They're the platform's answer to reporting problems that are awkward to solve in plain HTML - paginated tables that flow cleanly across page breaks, repeating headers and footers in printed output, charts, barcodes, QR codes, gauges, KPIs. Drop a block into your template, set its properties, and it renders.

Blocks are enrichers, not a wall. A report template is just HTML + Liquid; you can build one without using a single block. Most teams reach for them because the print-flow blocks in particular handle the hard parts of multi-page layout for free.

A catalog of built-in blocks ships out of the box; you can add more by installing a block plugin from the Marketplace or by building your own.

This reference groups blocks by category. Each entry describes what the block does, where you'd use it, and the key properties you'll bind in the editor.

Structural blocks

The skeleton of every page. Structural blocks define how everything else is arranged.

Body

The root container body holds everything visible on a page. Sets the page's overall padding and the default text direction.

Section

A semantic container section for a logical group of content - for example, the "Order summary" section of an invoice. Useful for applying shared styling and for accessibility.

Canvas

A free-positioning container canvas. Children are placed at absolute coordinates instead of flowing. Use when you need pixel-precise placement (e.g. a label on a fixed-size form).

Stack

A vertical or horizontal flow container stack - the most common layout primitive. Children stack along the axis with configurable gap, alignment, and wrapping.

Columns

A multi-column container columns with explicit column widths or fr-units. Children fill columns left-to-right.

Grid

A full CSS-grid container grid with named or auto-placed cells, gutters, and per-cell spans. Use for dashboard-like layouts where you want repeatable cells.

Divider

A horizontal or vertical rule divider. Mostly cosmetic - separates sections, table rows, or KPIs.

Content blocks

The things that hold the data.

Heading

A semantic heading heading (H1-H6). Bound to a Liquid expression or a literal string.

Text

A paragraph or block of running text text. Supports rich-text inline marks (bold, italic, links) and Liquid expressions inside {{ ... }}.

List

An ordered or unordered list list. Items can be authored manually or bound to a query result (one item per row).

Image

An embedded image image. Source can be a URL, an asset reference (asset://...), or a Liquid expression that resolves to one. Supports object-fit, alt text, and a fallback.

Table

A data table table with header, body, and optional footer rows. Columns are bound to fields from a query result. Tables paginate automatically across multi-page reports and respect the page's header/footer flow.

KPI

A single-value scorecard kpi - typically used for headline metrics ("Revenue this month", "Open tickets"). Properties bind a primary value, an optional comparison (e.g. month-over-month), a label, and an icon.

Progress

A linear or radial progress indicator progress bound to a numeric value (0-100 or a min/max). Useful for utilisation, completion, or capacity.

Gauge

A circular/dial gauge gauge for bounded numeric values. Like progress, but visualises a range with thresholds.

Charts

A few chart blocks ship out of the box. They all accept their data either inline or from a query result.

Bar chart

chart-bar - bar or column chart. Supports grouped, stacked, and percentage-stacked variants, configurable axes, legend, and tooltip.

Pie chart

chart-pie - pie or doughnut chart. Slice values come from a query result; labels can be the category field or a Liquid expression.

Candlestick chart

chart-candlestick - financial OHLC (open/high/low/close) candlestick chart. Common for revenue swings, stock-style charts, anything time-series with min/max bands.

More chart families are typically delivered as separate plugins to keep the core bundle small.

Codes and machine-readable blocks

Barcode

barcode - a linear barcode supporting Code 128, Code 39, EAN-13, UPC, ITF, and other common retail and logistics formats. Use for SKUs, picking labels, shipping documents.

QR code

qr-code - a QR code. Configurable error-correction level, foreground/background, and embedded logo. Use for product links, payment QR codes, ticketing.

Page-flow blocks

The blocks that make printed reports behave like real documents. They're the value-add of using blocks in the first place - solving print-layout problems that plain HTML can't.

page-header - content that repeats at the top of every page in a flow. Typical use: company logo + report title + date.

page-footer - content that repeats at the bottom of every page. Typical use: page numbers (Page {{page.number}} of {{page.total}}), legal text, contact info.

Page break

page-break - force a page break before or after the block. Useful when a long table or section should always start on a fresh page.

A worked example

Here's a sketch of an invoice template that mixes plain HTML with blocks. The HTML parts are just HTML; the blocks (in custom-element form) handle the things you'd otherwise have to engineer yourself.

<page-header>
  <img src="/assets/logo.svg" alt="Acme" />
  <h1>Invoice {{ invoice.number }}</h1>
  <p>Issued {{ invoice.date | date: '%d %b %Y' }}</p>
</page-header>

<section>
  <h2>Bill to</h2>
  <p>{{ invoice.customer.name }}</p>
  <p>{{ invoice.customer.address }}</p>
</section>

<table-block rows="{{ invoice.lines }}">
  <column field="description" label="Item" />
  <column field="quantity"    label="Qty" />
  <column field="unitPrice"   label="Unit" format="money" />
  <column field="subtotal"    label="Subtotal" format="money" />
</table-block>

<div class="totals">
  <kpi label="Total" value="{{ invoice.total | money }}" />
</div>

<page-footer>
  Page {{ page.number }} of {{ page.total }}
</page-footer>

The <page-header> and <page-footer> blocks repeat on every printed page; the <table-block> paginates rows cleanly across page boundaries. The <section>, <h1>, <p>, <img>, and <div> around them are plain HTML - the blocks coexist with whatever HTML you want to write.

The page-flow blocks (page-header, page-footer, page-break) are the ones most often forgotten - without them a multi-page report renders as one endless web page.

Custom blocks

If none of the above fits, write one. Custom blocks plug into the editor's palette and become bindable in exactly the same way as the built-ins. See Block plugins for the development guide.

Learn the binding model: Parameters, variables & queries.
Style a report consistently: Themes & styling.
Render text dynamically: Liquid templating.