Bullet

A bullet is a measure against a target, on a straight track, with qualitative ranges behind it. Each row is one measure. The bar is the value. The line across the track is the target. The bands are the ranges, worst to best.

When to use it

Use a bullet when the question is whether a measure has passed its target, and which range it sits in. Quota puts revenue past its target and profit still short. Against the bed marks does the same for three crops.

A bar compares categories. The bars do not sit on a target, and there are no poor, ok, and good bands behind them. A horizontal bar is still a bar. mark.orientation does not apply here. A gauge is one dial. A bullet is the straight form of a measure against a target: one row per measure, a marker you can see, and range bands. A linear gauge is this chart. bullet-chart repairs to bullet.

A handful of rows stays readable. Quota has two. Against the bed marks has three. A long ranking, with no target, is a bar.

Bullet, bar, and gauge

All three can show a value per name. The encoding is what changes.

type: "bullet" needs encoding.y for the measure. encoding.x is the row label. encoding.target is the marker field. mark.ranges names the band fields, worst to best. Each number in those fields is the upper edge of that band.

type: "bar" uses encoding.x and encoding.y and compares the bars with each other. It has no target channel and no range bands.

type: "gauge" stores metric.target on the dial and does not draw it. The bullet draws the target as a line. One gauge is one reading. A bullet can list several.

Data

Each row is one measure. Quota uses name, value, target, and the band fields poor, ok, and good. Against the bed marks uses crop, kilos, mark, and thin, fair, full. Café bags against the aim uses one band, wide.

Point encoding.x at the label, encoding.y at the measure, and encoding.target at the marker. mark.ranges is the field names, in order from the worst band to the best. The values must be the upper edges, and they are sorted before they are drawn. Omit the list and the row still has three bands, at half, three quarters, and the full scale.

A missing measure is skipped. The scale for a row runs at least to the value, the target, and the last band. Rows do not share one axis. Revenue at 275 and profit at 22 each fill their own track.

a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.

A spec that renders

This is the smallest bullet. version, type, encoding.y, and a11y.alt are required. One range field and a target are enough. The row label comes from encoding.x.

spec.json
{
  "version": "1",
  "type": "bullet",
  "data": [
    {
      "name": "Revenue",
      "value": 275,
      "target": 250,
      "good": 300
    }
  ],
  "encoding": {
    "x": "name",
    "y": "value",
    "target": "target"
  },
  "mark": {
    "ranges": [
      "good"
    ]
  },
  "a11y": {
    "alt": "Revenue is past its target."
  }
}

Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.

Import@chartkitdev/core/charts/bulletBundle@chartkitdev/core/extraFamilyStatistical
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
npm install @chartkitdev/core
npm install @chartkitdev/qwik

import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";

export const Panel = component$(() => {
  return <Chart spec={spec} />;
});
Angular
npm install @chartkitdev/core
npm install @chartkitdev/angular

import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";

@Component({
  standalone: true,
  imports: [Chart],
  template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
  spec = spec;
}
Custom element
npm install @chartkitdev/core
npm install @chartkitdev/element

import "@chartkitdev/element";

const chart = document.querySelector("chart-kit");
chart.spec = spec;

Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.

Examples

The rail switches among existing bullet specs. Quota is the core chart, two measures and three bands. Against the bed marks is three crops, and the size 880 by 240 wins over the preview default. Café bags against the aim is one row and one band, at 640 by 200.

Ranges

mark.ranges names the columns that draw the bands, worst first. Quota uses poor, ok, and good. Against the bed marks uses thin, fair, and full. Café bags against the aim uses only wide. Each value is that band's upper edge.

Off removes the list. The measure and the target stay, and the track falls back to three even bands. On puts that example's field list back. An example that omitted the list stays on the even bands.

mark.ranges
{
  "mark": { "ranges": ["poor", "ok", "good"] }
}

Target

encoding.target is the field for the marker. The marker is a line across the band. Quota points it at target. Against the bed marks points it at mark. Café bags against the aim points it at aim.

Off removes that channel. The value bar and the ranges stay, and the line goes away. On puts the example's field back. The other encoding channels are left as they were.

encoding.target
{
  "encoding": { "target": "target" }
}

Tooltip

Each row already prints its name and its value. The measure and the target marker also carry an SVG title with the value and the target. tooltip is the hover card, the same key as on a bar. Omit it and this control reads on. tooltip: false turns the card off. tooltip: true turns it on.

tooltip false
{
  "tooltip": false
}
tooltip true
{
  "tooltip": true
}

tooltip.fields and tooltip.position stay in the playground. Turning the card off and on again puts that object back. An example that omitted tooltip gets the key removed.

The rest of the spec

A bullet does not draw a legend. The row names are the labels. There is no orientation key. A qualitative color per band is not a separate option: the bands share the track color and step down in opacity, worst to best. Theme presets live on the playground, with the full option list.