# Bullet Chart

Bullet chart for a measure against its target and qualitative ranges — horizontal, vertical or as a KPI list.

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

## Install

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

## Import

```tsx
import { BulletChart, BulletChartProps, BulletChartVariant } from "@wunderui/react"
```

## Minimal usage

Then use it:

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

const data = [
  { name: "Revenue", value: 270, target: 250, poor: 150, ok: 225, good: 300 },
  { name: "Profit", value: 22, target: 26, poor: 20, ok: 25, good: 30 },
]

export function QuarterKpis() {
  return <BulletChart data={data} index="name" label="Quarter KPIs" />
}
```

Expected result: You should see two rows, each with three background bands, a measure bar and a short target line.

## When to use

### Use Bullet Chart for

- One measure against its target, over qualitative ranges (poor, ok, good)
- A list of KPIs that should line up for comparison
- More information than a gauge in the same height

### Use something else

- [Gauge Chart](https://wunderui.com/components/gauge-chart) for a single value on a dial
- [Progress Chart](https://wunderui.com/components/progress-chart) for completion without a target line
- [Radial Chart](https://wunderui.com/components/radial-chart) for progress as rings
- [Bar Chart](https://wunderui.com/components/bar-chart) for values without targets

## Keyboard

The plot is focusable: arrow keys move from KPI to KPI and the live region reads the name, value and target, like Direct: 42, target 45 (93% of target).

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the plot and away from it. The plot is one tab stop; so is every legend badge. |
| `ArrowRight` or `ArrowLeft` | Moves to the next or previous KPI. The tooltip follows, and a live region announces the one you are on. The first press starts at the first one (Left: the last one). |
| `Home` or `End` | Jumps to the first or last KPI. |
| `Escape` | Clears the active point. |
| `Enter` or `Space` | On a legend badge of a ChartCard: switches its series off or on. The last visible series stays on. |

## Behavior

What the chart does on its own and what the page decides.

- **Fields:** Each row is a KPI: the index names it, the value is the measure, and the target and range fields come from your data (defaults: target; poor, ok, good in ascending order).
- **Marks:** Three bands from the outermost in, the measure bar growing from zero, and the target as a short line with a card-coloured halo so it reads against every band.
- **Scale:** Each KPI has its own scale, drawn under its bar as tick marks with their values (left of the column on the vertical bullet when they fit). The list goes without; ticks turns them on or off.
- **Hover and labels:** Hovering a KPI dims the others to --chart-dim. The name and "value / target" never collide: on a narrow card the target goes first, then the name is shortened.
- **Attainment:** The tooltip shows Actual, Target and Attainment: the value divided by the target, in percent.
- **Layouts:** The bullet variant runs bars horizontally, vertical-bullet vertically, and bullet-list puts the name above each bar for a compact list.
- **Loading, empty and error:** The chart keeps its size while it loads, is empty or fails, so the card never jumps. Loading shows a skeleton; error adds a Try again button when a retry handler is set.
- **Legend:** A ChartCard shows series as badges. With two or more series each badge switches its series off, the last visible one stays on, and a legend of roles can be made static.
- **Data table:** The chart renders its data as a table for screen readers, in the same order as the plot.
- **Size:** The chart fills its container's width; you set the plot height. Text never scales: labels keep their size at every width.

## Motion

The enter sequence and the hover follow the motion tokens of the library.

- **Grow:** The measure bar grows from zero the first time the chart is in view, and again after loading or when new data arrives. You can turn the animation off.
- **Reduced motion:** With reduced motion on, the enter sequence is off and the chart appears at once. Tooltip, crosshair and every state still work.

## Anatomy

- `BulletChart`: Takes data with one row per KPI: an index for its name, a value for the measure, a target field and the range bounds in ascending order (poor, ok, good by default).
- `Plot`: The focusable region. Arrow keys move from KPI to KPI and the live region reads name, value and target, like Direct: 42, target 45 (93% of target), and the tooltip adds the attainment.
- `Marks`: Three bands from the outermost in, the measure bar growing from zero, and the target as a short line with a card-coloured halo so it reads against every band.
- `KPI labels`: The name of each row left of the bar (above it on the list variant), and the value at the end.
- `Tooltip`: Actual, Target and Attainment (value divided by target, in percent).
- `Loading, empty and error`: Five muted bars under the shimmer. The empty title defaults to No data for this period.
- `Data table and live region`: Actual, target and every range bound as columns, for screen readers.
- `Chart Scale`

## Best practices

### When to use

- Use BulletChart for KPIs with a target, such as revenue against quota. Use GaugeChart for a single value on a scale and LineChart when the trend matters.

### Do

- Give every row a target and range bounds in the same unit as the value. Each row has its own scale, so compare attainment, not bar length, between rows.
- Order the range fields from the lowest bound to the highest. The bands are drawn from the outermost, so unsorted bounds hide each other.
- Use the list variant for six or more KPIs, where rows are 36 px and read like a table; use the full bullet for two or three headline KPIs.

### Don't

- Don't leave out the target. Without it the chart is a bar over grey bands, and the point of the form is lost.
- Don't use the bands as decoration. If poor, satisfactory and good have no agreed thresholds, show the bar and the target only.

## API reference

### BulletChart

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | readonly ChartDatum[] |  | One object per slice / ring / axis. |
| index* | string |  | Field holding the label. |
| activeIndex | number \| null |  | The active point (hovered or focused) as an index into `data`, to control it yourself. `null` shows none. |
| animate | boolean |  |  |
| animationKey | string \| number |  |  |
| className | string |  | Extra classes for the root element of the chart. |
| colors | readonly ChartColor[] |  | Colours per row, in order (palette names or token expressions). |
| defaultActiveIndex | number \| null |  | The point that is active at first, for an uncontrolled chart. It shows the tooltip without a pointer. |
| description | string |  |  |
| emptyDescription | string |  | Text under the title in the empty state. |
| emptyTitle | string |  | Title of the message in the empty state. |
| errorDescription | string |  | Text under the title in the error state. |
| errorTitle | string |  | Title of the message in the error state. |
| height | number |  | Height of the plot frame in px. Default 280 (Figma small card plot). |
| hiddenSeries | readonly string[] |  | Labels of rows switched off in the legend: drawn faded. |
| label | string |  | Accessible name, e.g. the card title. |
| onActiveIndexChange | (index: number \| null) => void |  | Called with the index when the pointer or the arrow keys move to another point, and with `null` when they leave. Use it to show the hovered value in a headline. |
| onRetry | () => void |  | Shows a Try again button in the error state and calls this when it is pressed. |
| ranges | readonly string[] | ["poor", "ok", "good"] | Fields of the qualitative ranges (upper bounds, ascending), e.g. ["poor", "ok", "good"]. |
| state | "ready" \| "loading" \| "empty" \| "error" |  |  |
| target | string | "target" | Field of the target marker. Default "target". |
| ticks | boolean |  | Scale ticks along each bar (tick marks with their values). Default true for `bullet` and `vertical-bullet`; the compact `bullet-list` goes without. |
| tooltip | boolean |  |  |
| value | string |  | Field holding the value. Default "value". |
| valueFormatter | ChartValueFormatter |  |  |
| variant | "bullet" \| "vertical-bullet" \| "bullet-list" | "bullet" | Figma variant. Default `bullet`. |
| width | number |  |  |

## Examples

### States

### Scale

### Narrow cards

## In context

### Quota Attainment per Rep

Closed won against quota per rep.

### OKR Progress

Key results, current against target.

### Budget vs Actual

Department spend against budget with KPI cards.

## For AI agents

`get_component("bullet-chart")`

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