Skip to main content

BarChart

Bars — buckets, histograms, stacks, and categories. One component with three input modes; the histogram is BarChart in its bins mode, not a separate component.

src/examples/gallery-histogram.tsx
import {
  BarChart,
  ChartContainer,
  ChartRow,
  Layers,
  YAxis,
} from '@pond-ts/charts';
import { useSiteChartTheme } from '@site/src/theme/useSiteChartTheme';
import { responseTimeDistribution } from './lib/gallery-fixtures';

/** Response-time distribution: a value-axis histogram (`byColumn`, 10ms-wide
 *  bins) — the x axis is inferred from the bins, not declared. */
export default function GalleryHistogram({ width }: { width: number }) {
  const theme = useSiteChartTheme();
  const bins = responseTimeDistribution();

  return (
    <ChartContainer range={[0, 280]} width={width} theme={theme}>
      <ChartRow height={220}>
        <YAxis id="count" label="samples" min={0} pad={0.06} width={44} />
        <Layers>
          <BarChart bins={bins} column="count" gap={2} />
        </Layers>
      </ChartRow>
    </ChartContainer>
  );
}

Data contract​

Provide exactly one of:

  • series — a TimeSeries / ValueSeries (interval-keyed; each [begin, end) is a bar's span) with column, or a wide series with columns (stacked segments), or a Map<group, TimeSeries> with column (a series per group).
  • bins — byColumn records { start, end, ...aggregates } — the value-axis histogram.
  • categories — CategoryDatum[] ({ label, value }) → an ordinal category axis, vertical only.

Adapters: barsFromTimeSeries / barsFromValueSeries (single), stacksFromColumns / stacksFromGroups / stacksFromBins (stacked), categoryStack (categories), transposeRow (a wide row → categories).

Props​

PropTypeDefaultPurpose
seriesTimeSeries | ValueSeries | Map<string, TS>one-ofSource (single, stacked-by-columns, or per-group Map).
binsBinRecord[]one-ofbyColumn bins — the histogram mode.
categoriesCategoryDatum[]one-ofOrdinal category bars (vertical only).
columnstringwith series/binsValue column (single). column xor columns.
columnsreadonly string[]—Stacked segment columns, bottom → top.
asstring'default'Style role (single series only — ignored on stacks).
colorsRecord<string, string>—Per-group fill override for stacks.
binColorsreadonly (string | undefined)[]—Per-bin fill for a single-series zone chart.
orientation'vertical' | 'horizontal''vertical'Bar direction.
ordinalbooleanfalseFor bins: uniform [i, i+1] slots instead of numeric edges.
idstring—Stable identity — gates selection + hover.
axisstringrow defaultWhich <YAxis id> to scale against.
gapnumbertheme (1)Px gap between bars.

Variants​

  • Data mode — series (single / stacked / Map) vs bins (histogram) vs categories (ordinal). This is the axis-behaviour fork.
  • orientation — 'vertical' (default) or 'horizontal'.
  • column vs columns — a single value column, or stacked segments.
  • colors (per-group stacks) vs binColors (per-bin single-series zones).
  • ordinal — bins on a uniform ordinal band instead of their numeric spans.

Interaction & theming​

  • Cursor: the in-chart value cursor (flag / crosshair) is single-series vertical only — stacked and horizontal bars don't report a per-point readout.
  • Selection: id-gated — set id for clickable / hover-lit bars (a stack segment's identity is (id, key, group)).
  • Theming: the theme.bar slot (BarStyle); stacks colour per group via colors, so as is single-series only.

Cautions​

  • Histogram is a mode, not a component — bins + orientation.
  • Stacks baseline from 0 — the value axis must include 0; a <YAxis min> above 0 is unsupported for stacks. Negative/zero segments are skipped (diverging stacks are out of scope).
  • Horizontal puts value on x (x-kind 'value') — a horizontal histogram can't share a <ChartContainer> with time-series rows; it stands alone.
  • Exactly one of series / bins / categories, and column xor columns — violations throw.

See also​