# Sparkline

Small trend charts: KPI tiles, a metric list, a column strip and a win/loss strip, plus SparklineMini for tables and tiles.

- Category: Charts
- Page: https://wunderui.com/components/sparkline
- Tier: Core and Pro

## Install

Sparkline ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { Sparkline, SparklineMetric, SparklineMini, SparklineMiniProps, SparklineProps, SparklineVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { SparklineMini } from "@wunderui/react/charts"

export function TrendCell() {
  return <SparklineMini data={[48, 50, 49, 53, 55, 54, 58, 61]} aria-label="Up 27 % over 8 days" />
}
```

Expected result: You see a small green trend line, 96 by 32 px, rising from left to right.

## When to use

### Use Sparkline for

- A trend next to a number in a KPI tile or a metric list
- A tiny trend in a table row (SparklineMini)
- A daily strip of columns, or a win and loss strip, in a card

### Use something else

- [Line Chart](https://wunderui.com/components/line-chart) for a trend with axes, a tooltip and a legend
- [Area Chart](https://wunderui.com/components/area-chart) for volumes that need an axis
- [KPI](https://wunderui.com/components/kpi) for a single figure with a change
- [Metric Card](https://wunderui.com/components/metric-card) for a card with a figure, a chart and a menu

## Behavior

What the sparkline draws and what it leaves to the page.

- **Hover:** Sparklines take no focus and no keys; the accessible name carries the meaning, so write one that says what the trend is. The pointer follows the one hover model of the charts. SparklineMini dims the line and keeps a window around the hovered point, with a dot on it. The bar and win-loss strips keep the hovered bar at full strength (a pale bar comes up to full), dim the others to --chart-dim and show a compact tooltip beside the bar (labels name the values, tooltip={false} turns it off). Both hand the hovered index to onActiveIndexChange, for example to show its value next to the line.
- **Formats:** KPI tiles and the metric list read metrics (label, value, change, points). The bar and win-loss strips read data, with height, colour and highlight options.
- **Direction:** SparklineMini colours by direction (green up, red down, grey flat), and you can override it. The change in tiles and lists has a sign, so direction isn't only colour.
- **End point and new data:** SparklineMini ends on a dot that arrives with the line (endPoint turns it off). New data morphs the line from where it is instead of drawing it in again; fluid draws at the cell's real width, so the dot stays round.
- **Loading:** The loading state shows placeholders in the tiles' box, so the layout doesn't move when values arrive.

## Motion

The enter sequence and the hover follow the library's motion tokens.

- **Count and draw:** The number counts up to its value and the line draws in the first time the sparkline comes into view. You can turn it off.
- **Reduced motion:** With reduced motion the enter sequence is off and the chart appears at once. Every state still works.

## Anatomy

- `Sparkline`: Picks a format: KPI tiles and a metric list read metrics (label, value, change, points), while the bar and win-loss strips read plain data. A loading state shows placeholders.
- `SparklineMini`: The trend line, as line or area, 96 by 32 px by default or fluid to fill its cell, coloured by direction (green up, red down, grey flat). Give it an aria-label like Up 12.4% over 7 days.
- `Value and change`: The number, which counts up to its value, with the change under it (tiles) or beside it (list). It has a sign and a success or error colour, so direction isn't only colour.
- `Strip bars`: In the bar strip, one column per value with the highlighted bar solid and the rest pale. In the win-loss strip, green bars above the middle line and red below. The hovered bar keeps its strength and the others dim.
- `End`
- `Spotlight`
- `Active`

## Best practices

### When to use

- Use it where a number needs its recent trend in a few pixels: a KPI tile, a table cell, a list row. Use LineChart once people need axes, values or a tooltip.

### Do

- Always put the current value and the change next to the line. The line has no scale, so the number carries the meaning.
- Set an aria-label with the direction and period on every SparklineMini. Without it the label is generated from the first and last value.
- Use the same number of points and period for every row of a list. A seven-day line beside a 30-day line cannot be compared.

### Don't

- Don't compare the heights of two sparklines. Each is scaled to its own minimum and maximum, so a flat series and a volatile one can look alike.
- Don't use the win-loss strip for values that aren't a result of a period. Positive means a win and anything else a loss.

## API reference

### Sparkline

| Prop | Type | Default | Description |
|---|---|---|---|
| animate | boolean | true |  |
| className | string |  | Extra classes for the root element of the chart. |
| color | "indigo" \| "blue" \| "purple" \| "green" \| "orange" \| "pink" \| "yellow" \| "red" \| "grey" |  | `bar-sparkline`: colour of the bars (default indigo). |
| data | readonly number[] | [] | `bar-sparkline`, `win-loss-sparkline`: the values. |
| height | number | 48 | `bar-sparkline`, `win-loss-sparkline`: height of the strip (default 48). |
| highlight | number |  | `bar-sparkline`: the bar drawn solid (default the last one); the others are pale. |
| label | string | "Sparkline" |  |
| labels | readonly string[] |  | Bar and win-loss strips: names of the values (days, weeks) for the tooltip title. Default "3 of 12". |
| metrics | readonly SparklineMetric[] | [] | `kpi-tiles`, `metric-list`: one metric per tile / row. |
| onActiveIndexChange | (index: number \| null) => void |  | Bar and win-loss strips: called with the index of the hovered bar and with `null` when the pointer leaves. Use it to show the hovered value in a headline. |
| state | "ready" \| "loading" \| "empty" \| "error" | "ready" |  |
| tooltip | boolean | true | Bar and win-loss strips: the compact tooltip beside the hovered bar. Default true. |
| valueFormatter | (v: number) => string | (v) => String(v) |  |
| variant | "kpi-tiles" \| "metric-list" \| "bar-sparkline" \| "win-loss-sparkline" | "kpi-tiles" | Figma variant. Default `kpi-tiles`. |

### SparklineMini

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | readonly (number \| null \| undefined)[] |  |  |
| animate | boolean | true |  |
| aria-label | string |  | Accessible description, e.g. "Up 12 % over 7 days". |
| className | string |  |  |
| color | "indigo" \| "blue" \| "purple" \| "green" \| "orange" \| "pink" \| "yellow" \| "red" \| "grey" |  | Override the trend colour (token or palette name). |
| endPoint | boolean | true | A dot on the last value, like the end point of a Line chart. Default true. |
| fluid | boolean | false | Fill the parent's width (up to `width`) instead of a fixed size, for tiles and cards whose cells get narrow. The stroke keeps its weight. |
| height | number | 32 |  |
| onActiveIndexChange | (index: number \| null) => void |  | Called with the hovered point (pointer only) and with null when the pointer leaves, e.g. to show its value next to the line. |
| trend | "auto" \| "up" \| "down" \| "neutral" | "auto" | Colour by direction: `auto` compares first and last value (Figma · Trend). |
| variant | "line" \| "area" | "line" | `line` or `area` (Figma Sparkline Mini · Style). |
| width | number | 96 | Default 96 × 32 (Figma Sparkline Mini). |

## Examples

### States

### Sparkline Mini

### Hover and new data

## In context

### KPI Cards with Sparklines

Metric tiles with trend lines and a product table.

### Watchlist

A watchlist table with 1-day sparklines.

### Host List

Hosts with CPU sparklines.

## For AI agents

`get_component("sparkline")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
