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/API | Type | Default | Description |
|---|---|---|---|
data | readonly number[] or readonly T[] | required | Observations to bin. |
valueKey | numeric field of T | required with rows | Field holding each observation. |
ariaLabel | string | required | Accessible chart name. |
bins | number | number[] | 10 | Count hint, rounded to readable boundaries, or exact boundaries. |
domain | [number, number] | data extent, rounded | Fixed 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. |
color | CSS color | chart-1 | Bar color. |
valueLabels | boolean | false | Count or share above each bar. |
tooltip | boolean | true | Hover and keyboard tooltip. |
grid | boolean | true | Value grid lines. |
valueDomain | [number, number] | fitted, includes zero | Fixed count/share axis extent. |
valueTicks | number[] | rounded, spaced to the plot | Exact count/share axis ticks. |
formatValue | (value: number) => string | grouped number | Bin boundaries on the axis and in tooltip titles. |
formatMeasure | (value: number) => string | number, or percent for share | Counts (or shares, as fractions) on the axis, labels, and tooltips. |
emptyMessage | ReactNode | "No data to display" | Shown when no valid values exist. |
| Chart host props | see Chart | - | height, initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style. |
createHistogramDefinition(options) | function | - | Same options; returns an extensible TanStack definition. |
HistogramOptions, HistogramDatum, HistogramDefinition | types | - | 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
formatValueso each interval reads on its own. - Use exact
binsboundaries when comparing periods so bars mean the same interval.