Documentation › Charts
Handlebars (custom HTML) charts
Show query results with your own HTML template in a Handlebars chart - cards, lists and formatted messages, with helpers for dates and numbers.
The Handlebars chart displays a query's rows through a template you write in Handlebars and HTML. Use it when no standard chart fits: KPI cards with your own layout, a list of the week's top customers, or a sentence such as "Revenue this month: UGX 12.4M, 8% above target".
Basic use
- Create a chart and choose Handlebars.
- On Data, set the query as for a table: Query mode Aggregate with metrics and dimensions, or Raw records with columns.
- Write the template in Handlebars Template. The rows are available as
data, a list of rows. Each row's fields are named after the columns and metric labels. - Optionally add CSS in CSS Styles.
<ul class="top-branches">
{{#each data}}
<li><strong>{{this.branch}}</strong>: UGX {{formatNumber this.revenue 'en-UG'}}</li>
{{/each}}
</ul>
.top-branches { font-size: 16px; line-height: 1.8; }
.top-branches strong { color: #0b6e4f; }
Helpers
Formatting:
| Helper | Example | Result |
|---|---|---|
dateFormat |
{{dateFormat order_date format='D MMM YYYY'}} |
14 Mar 2026 |
formatNumber |
{{formatNumber revenue 'en-UG'}} |
1,234,567 |
stringify |
{{stringify this}} |
the row as JSON (handy while building) |
parseJson |
{{parseJson details}} |
a JSON text column as an object |
groupBy |
{{#groupBy data 'region'}}...{{/groupBy}} |
rows grouped by a field |
Comparison and logic (use them inside brackets with #if):
| Helper | Example |
|---|---|
eq, neq |
{{#if (eq status "Paid")}}✓{{/if}} |
gt, gte, lt, lte |
{{#if (gte growth 0)}}up{{else}}down{{/if}} |
and, or, not |
{{#if (and active (gt balance 0))}} |
ifx |
{{ifx overdue "Overdue" "On time"}} |
coalesce |
{{coalesce phone email "No contact"}} |
Text and maths: uppercase, lowercase, capitalize, truncate, contains, add, subtract, multiply, divide, round, floor, ceil. The full list is in the just-handlebars-helpers documentation.
A KPI card
Query: Aggregate, metrics revenue and target (no dimensions).
{{#each data}}
<div class="kpi">
<div class="label">Revenue this month</div>
<div class="value">UGX {{formatNumber this.revenue 'en-UG'}}</div>
<div class="{{ifx (gte this.revenue this.target) 'good' 'bad'}}">
Target: UGX {{formatNumber this.target 'en-UG'}}
</div>
</div>
{{/each}}
.kpi { font-family: inherit; padding: 8px; }
.kpi .label { color: #55666f; font-size: 13px; }
.kpi .value { font-size: 32px; font-weight: 700; }
.kpi .good { color: #0b6e4f; } .kpi .bad { color: #c0392b; }
Good to know
- HTML is cleaned for safety: scripts, inline event handlers (
onclick) and external frames are removed. - To show
{{literally, wrap it in a raw block:{{{{raw}}}} {{example}} {{{{/raw}}}}. - Templates only see the rows the query returns, up to the Row limit.
Something unclear or missing? Tell us and we'll improve this page.