# KPI Scorecard

> Multiple metrics in one clean tile. A Tableau viz extension in the TableauOps kit, hosted on your own dashboards.

Canonical: https://ext.tableauops.com/knowledge/kit/kpi-scorecard
Updated: 2026-09-18
Author: Eric Summers

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`](../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.
- **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).

## Get it

KPI Scorecard ships in the Extension Kit ($59). See it live on the [demo gallery](/kit/demo/kpi-scorecard).


---
Try it live: See it live — https://ext.tableauops.com/kit/demo/kpi-scorecard