Histogram

Bins one numeric field into contiguous bars to show a distribution, by count or share.

stable

Quick Preview

Asking prices

Active listings · ₦m

Usage

import { Histogram } from "@giddaa-housing/ui/histogram";

<Histogram
  data={listings}
  valueKey="price"
  bins={8}
  formatValue={(value) => `₦${value}m`}
  ariaLabel="Distribution of listing asking prices"
/>

<Histogram data={[3, 5, 8, 12, 13, 21]} ariaLabel="Days to first inquiry" />

Pass rows with a numeric valueKey, or a plain number[]. Missing and nonfinite values are omitted. Ticks sit on bin boundaries so each bar reads as an interval, and a hairline gap separates bins. Tooltips always show both count and share.

Examples

Default

Asking prices

Active listings · ₦m

Bin count or exact boundaries

bins takes a count hint (default 10), rounded to readable boundaries, or the exact boundaries. Pass boundaries when intervals mean something (weeks, ₦10m price bands) or must stay identical across periods. measure="share" plots each bin's share of all observations, and valueLabels prints it above each bar.

Time to first inquiry

Default bins: a count hint, rounded

Time to first inquiry

Share of listings · exact weekly bins

<Histogram
  data={days}
  bins={[0, 7, 14, 21, 28, 35]}
  measure="share"
  valueLabels
  formatValue={(value) => `${value}d`}
  ariaLabel="Share of listings by days to first inquiry"
/>

Props

Prop/APITypeDefaultDescription
datareadonly number[] or readonly T[]requiredObservations to bin.
valueKeynumeric field of Trequired with rowsField holding each observation.
ariaLabelstringrequiredAccessible chart name.
binsnumber | number[]10Count hint, rounded to readable boundaries, or exact boundaries.
domain[number, number]data extent, roundedFixed binned range; values outside it are omitted.
measure"count" | "share""count"Plot each bin's count or its share of all binned observations.
size"sm" | "md" | "lg"inherited, otherwise "md"Plot height and type.
colorCSS colorchart-1Bar color.
valueLabelsbooleanfalseCount or share above each bar.
tooltipbooleantrueHover and keyboard tooltip.
gridbooleantrueValue grid lines.
valueDomain[number, number]fitted, includes zeroFixed count/share axis extent.
valueTicksnumber[]rounded, spaced to the plotExact count/share axis ticks.
formatValue(value: number) => stringgrouped numberBin boundaries on the axis and in tooltip titles.
formatMeasure(value: number) => stringnumber, or percent for shareCounts (or shares, as fractions) on the axis, labels, and tooltips.
emptyMessageReactNode"No data to display"Shown when no valid values exist.
Chart host propssee Chart-height, initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style.
createHistogramDefinition(options)function-Same options; returns an extensible TanStack definition.
HistogramOptions, HistogramDatum, HistogramDefinitiontypes-Each datum carries x1, x2, count, share, and its source rows.

Accessibility

  • Provide a meaningful ariaLabel; focus the chart and use arrow keys to move between bins.
  • State the unit of the binned value in formatValue so each interval reads on its own.
  • Use exact bins boundaries when comparing periods so bars mean the same interval.

On this page