KPI

The KPI component (ui:kpi) renders key performance indicators as a grid of metric cards. Each card displays a label, a large value, and optional trend indicators with deltas. Use it to make statistics visually prominent and scannable.

Examples

View Glyph Markdown source

```ui:kpi
title: Business Metrics
metrics:
  - label: Revenue
    value: "$2.3M"
    delta: "+15%"
    trend: up
  - label: Users
    value: "48,200"
    delta: "+3,100"
    trend: up
  - label: Churn
    value: "2.1%"
    delta: "-0.3%"
    trend: down
    sentiment: positive
  - label: NPS
    value: "72"
```

Single metric

View Glyph Markdown source

```ui:kpi
metrics:
  - label: Total Revenue
    value: "$12.5M"
    delta: "+22%"
    trend: up
```

System snapshot (no deltas)

View Glyph Markdown source

```ui:kpi
title: System Status
columns: 4
metrics:
  - label: CPU
    value: "72%"
  - label: Memory
    value: "4.2 GB"
  - label: Disk
    value: "89%"
  - label: Network
    value: "1.2 Gbps"
```

KPI with units

Use the unit field to show units separately from values for better formatting.

View Glyph Markdown source

```ui:kpi
title: Server Performance
columns: 4
metrics:
  - label: Response Time
    value: "42"
    unit: ms
    delta: "-8ms"
    trend: down
    sentiment: positive
  - label: Throughput
    value: "1,250"
    unit: req/s
    delta: "+150"
    trend: up
  - label: Error Rate
    value: "0.02"
    unit: "%"
    delta: "-0.01%"
    trend: down
    sentiment: positive
  - label: Uptime
    value: "99.97"
    unit: "%"
    trend: flat
```

Negative trends with positive sentiment

When a metric decreasing is good news (like churn, errors, or costs), use sentiment: positive with trend: down to show a green color even though the arrow points down.

View Glyph Markdown source

```ui:kpi
title: Operational Improvements
columns: 3
metrics:
  - label: Customer Churn
    value: "1.8%"
    delta: "-0.5%"
    trend: down
    sentiment: positive
  - label: Support Tickets
    value: "142"
    delta: "-38"
    trend: down
    sentiment: positive
  - label: Avg Resolution Time
    value: "2.1"
    unit: hours
    delta: "-45min"
    trend: down
    sentiment: positive
```

Large metric grid (8 metrics)

Display up to 8 metrics in a comprehensive dashboard view. The grid automatically wraps based on the columns setting.

View Glyph Markdown source

```ui:kpi
title: Q4 Business Dashboard
columns: 4
metrics:
  - label: Revenue
    value: "$4.2M"
    delta: "+18%"
    trend: up
  - label: Gross Margin
    value: "68%"
    delta: "+3%"
    trend: up
  - label: Active Users
    value: "52,400"
    delta: "+4,200"
    trend: up
  - label: DAU/MAU Ratio
    value: "42%"
    delta: "+5%"
    trend: up
  - label: Churn Rate
    value: "2.1%"
    delta: "-0.4%"
    trend: down
    sentiment: positive
  - label: NPS Score
    value: "74"
    delta: "+6"
    trend: up
  - label: Support CSAT
    value: "4.6"
    unit: "/5"
    delta: "+0.2"
    trend: up
  - label: Avg Order Value
    value: "$127"
    delta: "+$12"
    trend: up
```

Responsive behavior

KPI metrics adapt to narrow containers. Below 500px, the grid reduces to at most 2 columns so metric values stay readable without horizontal overflow.

Properties

Property	Type	Required	Default	Description
`title`	`string`	No	—	Optional heading displayed above the metric grid.
`metrics`	`KpiMetric[]`	Yes	—	Array of 1—8 metric objects (see below).
`columns`	`1 \| 2 \| 3 \| 4`	No	`min(metrics.length, 4)`	Number of grid columns.
`markdown`	`boolean`	No	`false`	Enable inline markdown formatting (bold, italic, links, code) in text fields.

KpiMetric

Property	Type	Required	Default	Description
`label`	`string`	Yes	—	Metric name displayed above the value.
`value`	`string`	Yes	—	The metric value (string to allow formatted numbers like “$2.3M”).
`delta`	`string`	No	—	Change indicator (e.g. “+15%”, “-0.3%”).
`trend`	`"up" \| "down" \| "flat"`	No	—	Direction of change. Controls arrow icon.
`sentiment`	`"positive" \| "negative" \| "neutral"`	No	Derived from `trend`	Color of the delta. Defaults: up=positive (green), down=negative (red), flat=neutral (gray). Override to decouple direction from meaning (e.g. churn going down is positive).
`unit`	`string`	No	—	Optional unit label displayed after the value.

Markdown Support

Enable inline markdown formatting in metric labels by setting markdown: true:

View Glyph Markdown source

```ui:kpi
title: Business Metrics
metrics:
  - label: "**Monthly** Revenue"
    value: "$2.3M"
    delta: "+15%"
    trend: up
  - label: "Active [Users](https://example.com)"
    value: "48,200"
    delta: "+3,100"
    trend: up
  - label: "`churn_rate` Metric"
    value: "2.1%"
    delta: "-0.3%"
    trend: down
    sentiment: positive
markdown: true
```

Supported formatting: bold, italic, code, links

Learn more about markdown in components →

Accessibility

The component renders with role="region" and aria-label set to the title (or “Key metrics” if no title).
Each metric card uses role="group" with a combined aria-label including the label, value, and trend direction (e.g. “Revenue: $2.3M, up +15%”).
Trend direction is conveyed through text (“up”, “down”, “flat”) in the aria-label, not just color and icon.
Sentiment colors are supplemented by distinct arrow shapes (up/down/dash) so meaning is not color-dependent.