Components

Overview

Components are self-closing HTML-style tags that render query results as charts, tables, or KPI cards. Each component takes a data prop referencing a named query.

Choose the component that best fits your data:

• BigValue — single KPI number (total revenue, order count)
• LineChart — trends over time
• BarChart — comparing categories (vertical or horizontal)
• AreaChart — cumulative or stacked trends
• PieChart — proportional breakdown (best with 5-7 slices)
• DataTable — detailed rows for drilling into data

Syntax

<ComponentName data={query_name} prop="value" />

• Components are self-closing (/>)
• data uses curly braces: data={query_name}
• Other props use quotes: x="orders.city"
• Boolean props can be shorthand: horizontal

Component Reference

BigValue

Displays a single KPI metric as a large number. Optionally shows a comparison delta (▲/▼) against another measure from the same query.

<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" />
<BigValue data={kpis} value="orders.total_revenue" comparison="orders.total_cost" fmt="eur" comparisonTitle="vs cost" />
<BigValue data={kpis} value="orders.churn_rate" comparison="orders.churn_prev" fmt="pct1" downIsGood="true" comparisonTitle="vs last month" />

Comparison behavior:

• The delta is calculated as value - comparison. A positive delta means value > comparison.
• Arrow: ▲ when value exceeds comparison, ▼ when below, – when equal.
• Colors: green (▲) and red (▼) by default. When downIsGood="true", colors invert — a decrease shows green.
• Both value and comparison must be measures in the same query. The component reads from data[0] (first row).

LineChart

Renders a line chart, typically for time series. Supports multiple y columns, series splitting, and a secondary y-axis for combo charts.

<LineChart data={monthly_revenue} x="orders.created_at" y="orders.total_revenue" title="Revenue Trend" />
<LineChart data={trend} x="orders.created_at" y="orders.total_revenue,orders.count" />
<LineChart data={revenue_by_type} x="orders.created_at" y="orders.total_revenue" series="orders.type" />
<LineChart data={combo} x="orders.created_at" y="orders.total_revenue" y2="orders.count" yFmt="eur" y2Fmt="num0" />

BarChart

Renders a vertical bar chart. Add horizontal for horizontal bars. Supports multi-series with stacked or grouped display, and a secondary y-axis for combo charts (bars + line).

<BarChart data={revenue_by_city} x="orders.city" y="orders.total_revenue" />
<BarChart data={revenue_by_city} x="orders.city" y="orders.total_revenue" horizontal />
<BarChart data={revenue_by_type} x="orders.created_at" y="orders.total_revenue" series="orders.type" />
<BarChart data={revenue_by_type} x="orders.created_at" y="orders.total_revenue" series="orders.type" type="grouped" />
<BarChart data={combo} x="orders.created_at" y="orders.total_revenue" y2="orders.count" yFmt="eur" y2Fmt="num0" y2SeriesType="line" title="Revenue & Orders" />

AreaChart

Renders a filled area chart. Supports series splitting, stacked areas, and a secondary y-axis.

<AreaChart data={monthly_revenue} x="orders.created_at" y="orders.total_revenue" />
<AreaChart data={revenue_by_source} x="orders.created_at" y="orders.total_revenue" series="orders.source" type="stacked" />
<AreaChart data={combo} x="orders.created_at" y="orders.total_revenue" y2="orders.count" yFmt="eur" y2Fmt="num0" />

PieChart

Renders a pie/donut chart.

<PieChart data={by_status} name="orders.status" value="orders.count" title="Order Status" />
<PieChart data={by_status} name="orders.status" value="orders.total_revenue" title="Revenue Split" fmt="eur" />

DataTable

Renders query results as a sortable, paginated table. Click any column header to sort ascending/descending.

<DataTable data={top_products} />
<DataTable data={top_products} columns="orders.category,orders.total_revenue,orders.count" />
<DataTable data={top_products} rows="25" />
<DataTable data={top_products} rows="all" />

Sorting: Click a column header to sort ascending. Click again to sort descending. Null values always sort to the end. Numbers sort numerically, strings sort case-insensitively.

Formatting: Numbers right-align with tabular figures. Dates auto-detect and won't wrap. Use fmt for explicit formatting per column.

Column Children

For per-column formatting — especially when using Excel format codes that contain commas (e.g. $#,##0.00) — use <Column> children instead of the fmt prop:

<DataTable data={sales}>
  <Column field="orders.created_at" header="Date" fmt="shortdate" />
  <Column field="orders.total_revenue" header="Revenue" fmt="$#,##0.00" />
  <Column field="orders.count" header="Orders" fmt="num0" />
</DataTable>

Column children define column order, custom headers, and per-column formatting with no comma ambiguity. Self-closing <DataTable data={q} /> still works — auto-detects columns from data.

Secondary Y-Axis (Combo Charts)

LineChart, BarChart, and AreaChart support a secondary y-axis using the y2 prop. This renders a dual-axis chart with the primary series on the left axis and secondary series on the right — useful for overlaying metrics with different scales (e.g. revenue in EUR + order count).

<!-- Bars for revenue (left), line for count (right) -->

<BarChart data={monthly} x="orders.created_at" y="orders.total_revenue" y2="orders.count"
    yFmt="eur" y2Fmt="num0" y2SeriesType="line" title="Revenue & Orders" />

<!-- Two lines with different scales -->

<LineChart data={monthly} x="orders.created_at" y="orders.total_revenue" y2="orders.margin_pct"
    yFmt="eur" y2Fmt="pct1" title="Revenue & Margin" />

Key behaviors:

• The secondary axis renders on the right side with its own scale and formatting
• y2SeriesType overrides the chart type for y2 series — e.g. y2SeriesType="line" on a BarChart creates a bar + line combo
• Both y and y2 support comma-separated fields for multiple series on the same axis
• Tooltips format each series with the correct axis format (yFmt or y2Fmt)
• The secondary axis hides its grid lines to avoid visual clutter
• y2 is not supported with horizontal on BarChart (ignored when horizontal is set)

Layout

Auto BigValue Grouping

Consecutive <BigValue> components are automatically wrapped in a responsive grid — no <Grid> tag needed:

<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" />
<BigValue data={order_count} value="orders.count" title="Orders" />
<BigValue data={avg_order} value="orders.avg_order_value" title="Avg Order" />

This renders as a 3-column row. The grid auto-sizes up to 4 columns based on the number of consecutive BigValues. For more control, use an explicit <Grid> tag.

Grid

Wrap components in a <Grid> tag to arrange them in columns:

<Grid cols="3">
<BigValue data={total_orders} value="orders.count" title="Orders" />
<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" />
<BigValue data={avg_order} value="orders.avg_order_value" title="Avg Order" />
</Grid>

Layout Best Practices

Use ## for sections, not #. The # heading renders very large and wastes vertical space. Use ## for section titles and ### for subsections. Reserve # for the dashboard title only (which is set in frontmatter, not in the body).

Group related charts side by side. Wrap pairs of charts in <Grid cols="2"> to avoid long vertical scrolling:

<Grid cols="2">
<BarChart data={by_channel} x="orders.channel" y="orders.total_revenue" title="By Channel" />
<BarChart data={by_city} x="orders.city" y="orders.total_revenue" title="By City" horizontal />
</Grid>

Start each section with KPIs. Place <BigValue> cards at the top of a section for at-a-glance metrics, then follow with charts for detail.

Only Grid together components of similar height. Don't mix a <BigValue> with a chart in the same <Grid> row — the grid stretches both cells to the tallest item, leaving the BigValue card with a large empty area. Instead, place KPIs in their own row (consecutive BigValues auto-group) and pair charts with other charts of similar size.

Keep it compact. A good dashboard fits key information in 2-3 screens of scrolling. Use Grids, concise titles, and avoid unnecessary headings between every chart.

Formatting

Values are auto-formatted by default — numbers get locale grouping (1,234.56), dates display as "13 Jan 2025", and nulls show as "—". Override with named presets for common currencies and percentages, or use raw Excel format codes for full control.

Format Presets

Any string that isn't a preset name is treated as a raw Excel format code (ECMA-376). For example: fmt="orders.total_revenue:$#,##0.00".

Note: Percentage presets (pct, pct1, pct2) multiply by 100 per Excel convention — 0.45 displays as "45%".

Usage Examples

<!-- BigValue with currency -->
<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" fmt="eur2" />

<!-- DataTable with per-column formatting -->
<DataTable data={sales} fmt="orders.total_revenue:usd2,orders.created_at:shortdate,orders.margin:pct1" />

<!-- Chart with formatted tooltips -->
<BarChart data={monthly} x="orders.created_at" y="orders.total_revenue" yFmt="usd" />
<LineChart data={trend} x="orders.created_at" y="orders.growth" yFmt="pct1" />

Field Names

All field names in component props must be fully qualified with the view or cube name — the same format used in query blocks. For example, use value="orders.total_revenue" not value="total_revenue".

See Also

• Queries — query syntax and properties
• Examples — complete dashboard examples
• Dashboards — overview and deployment