A custom mark type that turns one measure + one date into an interactive metric card, bound to the Marks card (so it travels with the worksheet).
A "KPI" here defaults to a measure tracked over time, not a per-category breakdown. Drag one measure + one date and you get current value, period-over-period delta, and a trend sparkline.
Shared viz-extension techniques (reading encodings, live updates, the configure gear, selection → dashboard actions, responsive/no-scroll degradation) are not repeated here, they live globally in
reference/viz-extensions.md. This file covers only what's specific to the KPI Scorecard.
#What it is
- Current value (latest period) + ▲/▼ period-over-period delta pill.
- Trend chip (rising/falling/flat) and a sparkline with min / max / current dots.
- Live stats: min / max / avg / total.
- Scrub the sparkline to retarget the value + delta to a period; brush a date window to recompute over just that range; click / double-click resets.
- Play / replay / compare buttons (top right; Configure can hide them): play draws the chart in while the headline counts up; compare overlays the previous period (the window before a brush, or the latest half vs the half before) with both totals.
- Brush → dashboard actions: a brushed date window selects the matching worksheet marks so filter / highlight actions fire on the rest of the dashboard.
- Scales to fill any pane and sheds detail near the limits down to number-only (see the global responsive pattern).
#Encodings (Marks card)
| Tile | Required | Accepts |
|---|---|---|
| Measure | yes | one continuous measure (e.g. SUM(Sales)) |
| Date | yes | one date, use a continuous date (e.g. MONTH(Order Date)) |
| Color / Detail | no | one dimension, used as the breakdown for small multiples (e.g. Region) |
#Trend chart styling
- Style: Area + line (default), Smooth line (rounded Catmull-Rom curve), or Bars.
- Line / area color: optional override of the theme accent for the line, area fill, and bars. (Min/max/SMA markers keep their own colors so they stay distinguishable.)
- Moving averages: up to two simple-moving-average overlays (SMA 1 / SMA 2), each a dashed line with a small legend. Period = number of points; auto-skipped if longer than the series.
- Small multiples: when toggled on and a dimension is on Color/Detail, the trend area becomes a grid of mini trend charts, one per breakdown value, each with its own y-scale and latest value (capped at 24, with a "+N more" note). Scrub/brush apply to the single sparkline only, not the grid.
#Configure (the ⚙ gear, top-right)
Card title (defaults to the measure name), compare-to baseline, which direction is "good", card theme, trend chart style, line/area color, SMA 1 / SMA 2, small multiples, size, the sparkline toggle, and the dashboard-interaction toggle. All persisted in the workbook.
#Run it locally
From the repo root: python scripts/kitserve.py (serves every extension on 8765).
It answers on both IPv4 and IPv6 and resolves lib/ to _shared/lib; a plain
python -m http.server does neither, which is what makes a local extension load
as a blank or errored zone.
In Tableau, on a worksheet's Marks card → mark-type dropdown → Add Extension… → Access Local
Extensions → kpi-scorecard/manifest.local.trex. Drag a measure onto Measure and a
continuous date onto Date (try Sample - Superstore: SUM(Sales) + MONTH(Order Date) set
to continuous).
Reload after .html/.js/.css edits (right-click → Reload). For any .trex change,
remove and re-add the extension (Reload won't refresh the embedded manifest).