Skip to content

OrigamChartBullet ​

Compact KPI display chart (Stephen Few). Each series entry renders one bullet — qualitative range bands (poor / acceptable / good) as a coloured background, an actual-value bar overlaid on top, and a thin target marker tick for the comparative measure.

Quick start ​

vue
<script setup lang="ts">
import { OrigamChartBullet } from '@origam/components'
import type { IChartBulletDatum, IChartSeries } from '@origam/interfaces'

const series: Array<IChartSeries> = [
  {
    name: 'Revenue',
    data: [{ value: 420, target: 500, ranges: [{ to: 200 }, { to: 350 }, { to: 600 }] } as unknown as IChartBulletDatum]
  },
  {
    name: 'Profit Margin',
    data: [{ value: 28, target: 35, ranges: [{ to: 15 }, { to: 25 }, { to: 40 }] } as unknown as IChartBulletDatum]
  }
]
</script>

<template>
  <OrigamChartBullet
    :series="series"
    :categories="['Revenue', 'Profit Margin']"
    title="Sales Targets"
    subtitle="Q1 2026"
  />
</template>

Data shape ​

Each series entry must have exactly one datum in its data array. The datum must follow the IChartBulletDatum shape:

ts
interface IChartBulletDatum {
  value: number      // actual measured value
  target: number     // comparative target / goal
  ranges: Array<{
    to: number         // upper bound of this qualitative band
    color?: string     // optional fill (intent or raw CSS)
  }>
}

Bands are rendered in array order. Each band covers [previous.to, this.to]. Stephen Few recommends three bands: poor / acceptable / good.

Props ​

Core ​

PropTypeDefaultDescription
seriesArray<IChartSeries>requiredOne entry per bullet. Each entry's data[0] must be an IChartBulletDatum.
categoriesArray<string>[]Labels rendered beside each bullet. Falls back to series[i].name.
titlestringundefinedTitle above the chart.
subtitlestringundefinedSubtitle below the title.

Visual ​

PropTypeDefaultDescription
barColorTIntent | string'primary'Fill colour of the actual-value bar.
targetColorTIntent | string'danger'Stroke colour of the target marker tick.
rangeColorsArray<TIntent | string>['danger', 'warning', 'success']Fallback palette used when range.color is omitted. Cycled in array order.
orientationTDirection'horizontal''horizontal' renders labels left, bars right. 'vertical' renders labels bottom, bars upward.
barThicknessnumber0.45Fraction of the slot height (horizontal) or slot width (vertical) used for the value bar. Range [0, 1].
colorSchemeArray<TIntent | string>[]⛔ Sans effet sur ce composant — the value bar uses a single uniform fill (barColor) and range bands use their own palette (rangeColors) — there is no per-series identity for a rotating palette to drive. La prop reste declaree (elle est heritee d'IChartBaseProps) et emet un avertissement de developpement si elle est passee. Voir #426.

Behaviour ​

PropTypeDefaultDescription
showAxisbooleantrueToggle the quantitative axis line and tick labels.
showLegendbooleanfalseToggle the legend block.
legendPositionTChartLegendPosition'bottom'Anchor of the legend.
showTooltipbooleantrueToggle the hover tooltip.
animatedbooleantrueAnimate bars on first paint. Respects prefers-reduced-motion.
animationDurationnumber600Animation duration in ms.
xAxisFormat(v: string | number) => stringundefinedAxis tick formatter (horizontal orientation).
yAxisFormat(v: number) => stringundefinedAxis tick formatter (vertical orientation).

Inherited from IChartBaseProps ​

height, aspectRatio, and all dimension / margin / padding / rounded / elevation / bgColor props.

colorScheme is also inherited but has no effect on this component (see Caveats).

Emits ​

EventSignatureDescription
point-click(point: IChartPoint, event: MouseEvent | KeyboardEvent)Fired when a value bar is clicked or activated via keyboard.
legend-click(series: IChartSeries, index: number)Fired when a legend entry is clicked.
series-toggle(series: IChartSeries, visible: boolean)Fired after a visibility flip from a legend click.

Slots ​

SlotBindingsDescription
tooltip{ point, series, category, bullet, delta }Override the default tooltip body. delta is Math.round(value / target * 100).
empty—Render when series is empty or every series is hidden.
title—Replace the title + subtitle block.
legend-item{ series, index, visible }Replace one legend entry.

Behaviour notes ​

Responsive drawing surface (#1324). The SVG viewBox follows the measured box of the chart (useChartSize, a ResizeObserver), not a fixed 600 × 400 canvas. The plot fills the container width and height, the geometry is recomputed, and text, strokes and markers keep their real pixel size instead of being scaled with the viewBox. Until the box is measured (SSR, first paint) the 600 × 400 fallback is used, so hydration is unchanged. Give the chart a height / aspectRatio to change the box ratio.

Accessibility ​

  • Root is a native <figure> carrying aria-label — the title prop when given, otherwise the translated origam.chart.bullet.aria_label. The fallback is a locale key, not an English literal, so it follows the active locale (#567).
  • Inner <svg> carries role="group" plus <title> and <desc> for screen readers.
  • The chart is a single tab stop (roving tabindex, #1333): Tab enters it once, the arrow keys move between points, Tab leaves it — see the key table in the OrigamChart page.
  • Each value bar (<rect>) has role="button", and aria-label describing category / value / target / achievement %.
  • Keyboard: Enter and Space fire point-click on the focused bar.
  • Animation respects prefers-reduced-motion: reduce.

Examples ​

Custom tooltip with delta % ​

vue
<OrigamChartBullet :series="series" :categories="categories">
  <template #tooltip="{ category, bullet, delta }">
    <div>
      <strong>{{ category }}</strong>
      <span>{{ bullet?.datum?.value }} / {{ bullet?.datum?.target }}</span>
      <span>{{ delta }}% achievement</span>
    </div>
  </template>
</OrigamChartBullet>

Vertical orientation ​

vue
<OrigamChartBullet
  orientation="vertical"
  :series="series"
  :categories="categories"
  :height="320"
/>

Custom range per band ​

vue
const series = [{
  name: 'Score',
  data: [{
    value: 72,
    target: 80,
    ranges: [
      { to: 40, color: '#ef4444' },
      { to: 65, color: '#f97316' },
      { to: 100, color: '#22c55e' }
    ]
  }]
}]

Caveats ​

  • colorScheme has no effect (#426). It's inherited from IChartBaseProps and stays on the public API for consistency across chart types, but the value bar uses a single uniform fill (barColor) and the range bands use their own dedicated palette (rangeColors) — there's no per-series identity a rotating palette could drive. Passing it logs [origam] <OrigamChartBullet> prop "colorScheme" has no effect on this component: … once to the console in dev builds (silent in production). Neither wiring a fake behaviour nor removing the prop was on the table — see the #426 decision.

Composable reference ​

OrigamChartBullet does not ship a standalone composable — all geometry is computed inside the component. Tooltip rendering is delegated to OrigamChartTooltip and legend to OrigamChartLegend.

Browser support ​

SVG-only rendering — no canvas. Works in all modern browsers (Chrome 88+, Firefox 85+, Safari 14+, Edge 88+).

Token reference ​

TokenDefaultDescription
--origam-chart---gap12pxGap between header / body / legend grid areas.
--origam-chart---padding12pxOuter padding of the chart container.
--origam-chart---background-colortransparentContainer background.
--origam-chart__bullet-range---opacity0.55Opacity applied to all range bands.
--origam-chart__bullet-target---stroke-width3Width of the target tick stroke.
--origam-chart__axis-label---colorvar(--origam-color-text-secondary)Axis and category label colour.
--origam-chart__axis-label---font-size0.75remAxis tick label font size.
--origam-chart__axis-line---colorvar(--origam-color-border-subtle)Axis baseline stroke colour.
--origam-chart---animation-duration600msDuration of the fade-in animation.