Bullet

Creates a bullet graph from an array of data: one compact bar per row reading its value against qualitative bands, with a target marker, an optional forecast bar, and a value axis. Rows stack top to bottom, or side by side with orient("vertical").

Basic example

Each row becomes a bullet: its value as a bar, its target as a marker across the band, and bands as shades behind them. Threshold values split the domain into bands that step from the strongest shade to the lightest.

bulletSize

The most each bullet's band can be thick, in pixels (40 by default). Bullets never grow past it, so a tall chart with few rows centers them with space around; raise it (e.g. bulletSize: 120) to let rows fill more of the height, or lower it for a compact list. The measure, forecast, and target scale with the band.

measureSize

The measure bar's thickness, as a fraction of the band's thickness.

Key performance indicators

Stephen Few’s classic set of KPIs. bands and domain can be functions of the row, so each measure gets its own qualitative ranges and scale, and subLabel adds the unit under each name.

subLabel

Accessor for a smaller second label under each row's name, such as its unit.

Shared domain with forecast

sharedDomain reads every bullet against one scale, labeled by a single axis. A forecast (or any comparative measure) draws as a wider, paler bar behind the measure.

sharedDomain

Whether every bullet reads against one shared domain, labeled by a single value axis, instead of each bullet fitting its own.

forecast

Accessor for each row's forecast (or other comparative measure), drawn as a wider, paler bar behind the measure. A data key, a function, a number shared by every row, or false for none.

Vertical

orient("vertical") lines the bullets up as columns, with values growing upward and each name above its bullet.

orient

Which way the bullets run: "horizontal" (default) stacks them as rows with values growing rightward; "vertical" lines them up as columns with values growing upward.

horizontalvertical

bulletSize

Colored bands

Bands take the same {min, max, color} objects as Gauge’s. With colored bands, a neutral measure and a dark target read best; each measure is outlined in the background color so it separates from the band behind it.

const config = {
  data: [
    {id: "CPU", value: 64, target: 75},
    {id: "Memory", value: 81, target: 75},
    {id: "Disk", value: 37, target: 75},
  ],
  bands: [
    {max: 60, color: "#2b8a3e"},
    {max: 85, color: "#e67700"},
    {color: "#c92a2a"},
  ],
  domain: [0, 100],
  shapeConfig: {fill: "#f1f3f5"},
  targetConfig: {stroke: "#1f2328"},
};

Small multiples

With facet, each panel draws its own stack of bullets, and each measure reads against the same domain in every panel, so Revenue in one region compares directly with Revenue in another.

Compact

ticks(false) drops the axes for a compact sparkline-style list, and a number for target gives every row the same goal.

bulletSize

target

Accessor for each row's target, drawn as a marker across the band. A data key, a function, a number shared by every row, or false for none.

Classic (Few) style

Measures take the palette’s colors by row by default. Stephen Few’s original design draws every measure in one dark neutral over gray bands: a single shapeConfig.fill gives that look.

const kpis = [
  {
    id: "Revenue",
    unit: "US$, in thousands",
    value: 270,
    target: 250,
    ranges: [150, 225, 300],
  },
  {id: "Profit", unit: "%", value: 22.5, target: 27, ranges: [20, 25, 30]},
  {
    id: "Order Size",
    unit: "US$, average",
    value: 410,
    target: 550,
    ranges: [350, 500, 600],
  },
  {
    id: "New Customers",
    unit: "count",
    value: 1650,
    target: 2100,
    ranges: [1400, 2000, 2500],
  },
  {
    id: "Satisfaction",
    unit: "out of 5",
    value: 4.5,
    target: 4.2,
    ranges: [3.5, 4.25, 5],
  },
];

const config = {
  data: kpis,
  bands: d => d.ranges.slice(0, -1),
  domain: d => [0, d.ranges[d.ranges.length - 1]],
  subLabel: "unit",
  shapeConfig: {fill: "#333333"},
};

Tall bullet

Bullets are at most bulletSize pixels thick (40 by default) and centered in the space they’re given, so a chart with few rows keeps them compact. Raise bulletSize to let a bullet fill more of a tall chart; the measure, forecast, and target scale with it.

bulletSize

measureSize

The measure bar's thickness, as a fraction of the band's thickness.

Textures and images

Measure bars take shapeConfig.texture and shapeConfig.backgroundImage like any other Rect. The forecast bar follows the measure’s texture unless forecastConfig.texture sets its own, and takes its own forecastConfig.backgroundImage.

measureSize

The measure bar's thickness, as a fraction of the band's thickness.

Configuration

import {Bullet} from "@d3plus/core";

Extends Viz.

Filter 43 config keys

activefalse | function

The active callback function for highlighting shapes.

axisConfig{shapeConfig: {fill, stroke, strokeWidth, labelConfig}}

Styles the bullets' static parts: shapeConfig.fill colors the empty track, shapeConfig.stroke/strokeWidth the tick marks, and shapeConfig.labelConfig (fontColor, fontFamily, fontSize) the tick and row labels. Unset colors follow the chart's background, so the bullets read on light and dark themes alike.

bands(number | GaugeBand)[] | functionDefault []

The qualitative ranges behind each measure (e.g. poor / satisfactory / good). Either threshold values, [60, 85], which split the domain into three bands, or Gauge-style band objects, [{max: 60}, {max: 85, color: "#ffd43b"}, {}]. Bands without a color are shades of one hue, contrasting most with the background first and stepping lighter. A function (d, i) => bands gives each row its own bands.

bulletSizenumberDefault 40

classNamestring | array.<string> | undefined

CSS classes added to the outermost element this chart or component draws into, next to its fixed d3plus classes, so page CSS can target it: a chart's root <svg class="d3plus-viz"> (its <canvas> with the Canvas renderer) and a standalone component's <svg>. Takes a space-separated string or an array. A new value replaces the classes the previous one added; unset adds none. Tooltips take their own tooltipConfig.className.

colorDefaultscolordefaultsconfig

Overrides the default colors used when assigning fills from data and choosing legible text colors: dark and light (the text colors picked for contrast against a background), missing (null/undefined values), on/off (true/false values), sequential (the anchor hue for magnitude ramps), and scale (the categorical palette, given as a d3 ordinal scale or an array of colors). Keys are merged into the current defaults, and a Viz passes its overrides down to the shapes and components it draws.

configd3plusconfig

Methods that correspond to the key/value pairs and returns this class.

datastring | array.<datapoint> | object

The primary data array used to draw the visualization. The value passed should be an Array of objects or a String representing a filepath or URL to be loaded. The following filetypes are supported: csv, tsv, txt, and json.

If your data URL needs specific headers to be set, an Object with a "url" and "headers" (or any other fetch request option) may also be passed. An Object with any other key is a data row, not a request.

Additionally, a custom formatting function can be passed as a second argument to this method. This custom function will be passed the data that has been loaded, as long as there are no errors. This function should return the final array of obejcts to be used as the primary data array. For example, some JSON APIs return the headers split from the data values to save bandwidth. These would need be joined using a custom formatter.

If you would like to specify certain configuration options based on the yet-to-be-loaded data, you can also return a full config object from the data formatter (including the new data array as a key in the object).

To re-fetch a URL on an interval and redraw when its data changes, set dataPollingInterval; each poll runs the same formatter.

Defaults to an empty array ([]).

domain[number, number] | function

The [min, max] each bullet spans, or a function (d, i) => [min, max] for per-row domains. Either end may be left undefined to come from the row's values (measure, target, forecast) and band edges, rounded outward to nice numbers and always including zero.

Splits the chart into small multiples: a grid of equally sized panels, one per distinct value of this data key or accessor, each drawing the chart for that value's rows. The panels share one legend, color scale, title, and timeline, color each series the same way, and hover, tooltips, and legend clicks apply across all of them. Pass false to draw a single chart. See facetConfig for the grid's layout and shared scales.

facetConfigfacetconfig

Configuration for small multiples (see facet), merged into the current config: - columns / rows: the grid's shape. Chosen by default to make the panels as large as the chart's shape allows. - padding: the space between panels, in pixels (default 20). - sort: panel order — "ascending" (default), "descending", "data" (first appearance), a comparator over facet values, or an Array of values. - scales: "shared" (default) gives every panel of a chart with axes the same x/y domains; "independent" fits each panel to its own rows. Funnel defaults to "independent" (each panel sized to its own widest stage); "shared" sizes every panel against the widest stage across all panels. PolarArea and RadialBar default to "independent" (each panel's rings and ticks fit its own values); "shared" gives every panel the same value domain. - axes: with shared scales, "outer" (default) labels the axes only along the grid's left and bottom edges; "all" labels every panel. An object sets each axis on its own, as in {x: "all", y: "outer"}: every panel labels its x axis, only the left column labels its y axis, and the panels' plot areas line up. BumpChart defaults to "all", and Marimekko labels its categories on every panel and its 0–100% share axis only along the outer edge, even with independent scales. - title: a (value, data) => string function for each panel's title, or false to hide panel titles. - titleConfig: TextBox config for the panel titles (fontSize, fontWeight, fontColor, textAnchor, padding, …).

fontFamilystring | array.<string>

The font family used throughout the visualization.

forecaststring | number | function | falseDefault "forecast"

Accessor for each row's forecast (or other comparative measure), drawn as a wider, paler bar behind the measure. A data key, a function, a number shared by every row, or false for none.

forecastConfig{size, opacity, fill, texture, backgroundImage, backgroundImageFit}Default {opacity: 0.35, size: 0.6}

Styles the forecast bar: size (its thickness as a fraction of the band's), opacity, fill and texture (the measure's by default), and backgroundImage/backgroundImageFit (none by default), each a value or a (d, i) accessor.

groupBystring | function | array.<string | function>

Defines the mapping between data and shape. The value can be a String matching a key in each data point (default is "id"), or an accessor Function that returns a unique value for each data point. Additionally, an Array of these values may be provided if the visualization supports nested hierarchies.

highlightfalse | function

Persistently emphasizes the data points matching the given predicate: the matching marks keep their color while every other mark is de-emphasized to a neutral gray (the "emphasis" form — highlight one series, gray the rest). Unlike hover/active (transient, opacity-based), highlight is a standing state that survives pointer movement. Pass false to clear it.

hoverfalse | function

The hover callback function for highlighting shapes on mouseover.

legendboolean | functionDefault function

Each bullet is labeled at its start, so the legend only shows when its entries group the bullets (e.g. colored by a coarser category).

localestring | object

The locale used for all text and number formatting. Supports the locales defined in d3plus-format. The locale can be a complex Object, a locale code (like "en-US"), or a 2-digit language code (like "en"). If a 2-digit code is provided, the "findLocale" function is used to identify the most approximate locale.

measureSizenumberDefault 0.35

The measure bar's thickness, as a fraction of the band's thickness.

onstring

Event listener for the specified event typenames. Mirrors the core d3-selection behavior.

orient"horizontal" | "vertical"Default "horizontal"

Which way the bullets run: "horizontal" (default) stacks them as rows with values growing rightward; "vertical" lines them up as columns with values growing upward.

parentunknown

Parent config used by the wrapper.

renderfunction

Draws the visualization given the specified configuration.

rendererboolean | "svg" | "canvas"

Selects which @d3plus/render backend paints the visible output. "svg" = SvgRenderer (default), "canvas" = CanvasRenderer. Boolean arguments both normalize to "svg".

selectstring | htmlelement

The SVG container element as a d3 selector or DOM element. Defaults to undefined.

shapeConfigd3plusconfigDefault {stroke: () => chartBackground(viz), strokeWidth: MEASURE_OUTLINE}

Configuration object with key/value pairs applied as method calls on each shape.

Styles each measure bar like any other Rect: fill (the row's color by default), texture, backgroundImage/backgroundImageFit, and an outline in the chart's background color, so a bar stays distinct over a band of a similar color. Set shapeConfig.stroke/strokeWidth to override the outline; a neutral fill gives Stephen Few's classic single-color look.

sharedDomainbooleanDefault false

Whether every bullet reads against one shared domain, labeled by a single value axis, instead of each bullet fitting its own.

subLabelstring | function | falseDefault false

Accessor for a smaller second label under each row's name, such as its unit.

targetstring | number | function | falseDefault "target"

Accessor for each row's target, drawn as a marker across the band. A data key, a function, a number shared by every row, or false for none.

targetConfig{size, stroke, strokeWidth}Default {size: 0.75, strokeWidth: 3}

Styles the target marker: size (its length as a fraction of the band's thickness), stroke (the text color by default), and strokeWidth, each a value or a (d, i) accessor.

thresholdnumber | function

The threshold value for bucketing small data points together, as a share of the total. On a stacked Plot, the series whose summed value across every position is under that share of the whole chart's total merge into one series, stacked on top. A bucket needs at least two items, and its tooltips list them. Off (0) by default on Plot charts.

thresholdKeystring | function

Accessor for the value used in the threshold algorithm. A stacked Plot defaults to its stacked value.

tickFormatfunctionDefault function

Formats the tick labels. Defaults to the locale's abbreviated number format.

ticksnumber | number[] | false

The value axis ticks: a target count, an explicit array of values, or false for no axis. By default each axis fits as many ticks as its labels allow, always labeling both ends of the domain.

timestring | false | function

Accessor function or string key for the time dimension of each data point.

timelineDefaultstring | date | array.<string | date>

The starting time or range for the timeline. Can be a single Date/String, or an Array of 2 values representing the min and max.

tooltipConfigtooltipconfigDefault {tbody: (d: DataPoint, i: number) => bulletTooltipRows(viz, d, i)}

Lists each row's Value, Target, and Forecast in the tooltip body.

totalstring | boolean | function

Accessor function or string key for the total value displayed in the visualization.

translatefunction

Defines how informational text strings should be displayed. By default, this function will try to find the string in question (which is the first argument provided to this function) inside of an internally managed translation Object. If you'd like to override to use custom text, simply pass this method your own custom formatting function.

valuestring | functionDefault "value"

Accessor for each row's measure: a data key or a function.

valueFormatunknownDefault function

Formats the values in tooltips and aria labels, as (value, datum) => string. Defaults to the locale's abbreviated number format.

zoombooleanDefault false

Zooming and panning don't help read a bullet, so they're off by default.