Bullet Chart
Bullet chart for a measure against its target and qualitative ranges — horizontal, vertical or as a KPI list.
Playground
Installation
Bullet Chart comes with WunderUI Core and Pro, in the package from your plan. See the plans.
The charts live in their own entry point: import the chart, its card and its hooks from @wunderui/react/charts, not from @wunderui/react.
Then import what you need:
import {
BulletChart,
BulletChartProps,
BulletChartVariant,
} from "@wunderui/react/charts"Then use it:
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 for
- Gauge Chart for a single value on a dial
- Progress Chart for completion without a target line
- Radial Chart for progress as rings
- Bar Chart for values without targets
States
Loading, empty and error keep the chart's size, so the card never jumps. Add a retry handler and the error state offers a Try again button.
Keyboard interactions
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).
- TaborShiftTab
- Moves focus to the plot and away from it. The plot is one tab stop; so is every legend badge.
- ArrowRightorArrowLeft
- 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).
- HomeorEnd
- Jumps to the first or last KPI.
- Escape
- Clears the active point.
- EnterorSpace
- On a legend badge of a ChartCard: switches its series off or on. The last visible series stays on.
Behavior and motion
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.
- 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 puts one measure next to its target over qualitative ranges (poor, satisfactory, good). Each row is a KPI, and it packs more than a gauge into the same height.
Quarter KPIs
| name | Actual | Target | poor | ok | good |
|---|---|---|---|---|---|
| Revenue | 270 | 250 | 150 | 225 | 300 |
| Profit | 22 | 26 | 20 | 25 | 30 |
| New customers | 1.7k | 2.1k | 1.4k | 2k | 2.5k |
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).
- data-slot="chart-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.
- data-slot="chart-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.
The name of each row left of the bar (above it on the list variant), and the value at the end.
- data-slot="chart-tooltip"
Actual, Target and Attainment (value divided by target, in percent).
- data-slot="chart-message"
Five muted bars under the shimmer. The empty title defaults to No data for this period.
Actual, target and every range bound as columns, for screen readers.
Best practices
- 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.
- Do
Order the range fields from the lowest bound to the highest. The bands are drawn from the outermost, so unsorted bounds hide each other.
- Do
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
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
One table for BulletChart. It is a plain component, so the table lists every prop; the ChartCard around it takes its own props, and the chart works without one.
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).
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("bullet-chart")The full library index for assistants is at /llms.txt.