Skip to content
InsightCharts

Search

Search guides and components

Histogram

Bins a numeric field and shows how many rows fall in each bin, as touching bars on a continuous axis.

Use when
Showing the shape of a distribution for one numeric variable with roughly 50 rows or more: its centre, spread, skew, gaps and multiple peaks.
Avoid when
Comparing distributions across several groups (use box plot or beeswarm chart); under about 50 rows, where every observation can be shown (use strip plot or beeswarm chart); counts by category (use bar chart).

Preview

The median commute of 90 surveyed employees was 34.5 minutes

One-way commute time, in 5-minute bins

Illustrative data

Composition

  1. Atoms61
  2. Molecules19
  3. Templates20

Used in

No molecule or template lists histogram in its composes. It still fits any slot that takes a component.

Installation

$ pnpm dlx shadcn@latest add @insightcharts/histogram

The CLI copies the source into your project and needs the @insightcharts registry in components.json; see installation. With the package, import it by name:

import { Histogram } from "insightcharts";

Examples

Large sample, 10-minute bins

Finish times of 1,200 marathon runners

Minutes, in 10-minute bins. The line marks the median.

Illustrative data

Skewed, with mean and median

Household income distribution

Share of households in each $10,000 bin, with the mean and the median marked

Illustrative data

Two peaks

Waiting time between Old Faithful eruptions

Minutes between eruptions, 272 observations

Illustrative data modelled on the Old Faithful geyser dataset

Stress: few rows, many bins

11 of 15 support tickets closed within 7 days

Days to resolution, 15 support tickets

Illustrative data

Props

PropTypeDefaultDescription
valuerequiredstringNumeric field to bin.
binsnumberApproximate number of bins; the width is rounded to a tidy step. Default: from the row count.
stepnumberExact bin width in value units. Overrides bins.
medianbooleanfalseVertical marker at the median.
meanbooleanfalseVertical marker at the mean.
normalizebooleanfalseShare of rows per bin instead of a count.
countLabelstringTitle for the count axis, e.g. "Runners".
Common chart props 29

Every chart built with defineChart accepts these on top of its own props.

PropTypeDescription
dataDataInputRows, CSV text, a URL, { url, path }, an async function, or an Arrow-style table. Omit inside <InsightData>.
transformTransform | Transform[]A pipeline of transforms applied before drawing.
titlestringThe title. One plain statement of what the data shows, with the number and the period ("Monthly churn fell from 4.2% to 2.1% in 2024"), or a plain label ("Monthly churn, 2024"). One clause, no figures of speech.
subtitlestringMeasure, unit, population, period.
sourcestringData source, shown as "Source: ...".
notestringMethod notes or caveats.
heightnumber | stringCSS height of the plot. Default 360.
aspectnumberWidth / height. Overrides height.
highlightstring | string[]The entity (or entities) the title is about. Every other series is drawn in grey.
annotationsAnnotation[]Reference lines, shaded bands and callouts, in data coordinates.
formatFormatSpecHow to print values: "compact", "percent", "currency:USD", "{value} kg", Intl options, or a function.
legendbooleanShow the legend. Default: shown when there are two or more series.
selectboolean | stringMake marks clickable to filter. Inside <InsightData> the selection filters every other chart. Pass a field name, or true to use the chart's category field.
onSelect(values: string[], field: string) => voidCalled with the selected values whenever the selection changes.
optionEChartsOption | ((option: EChartsOption, ctx: BuildContext) => EChartsOption)Deep-merged over the generated ECharts option, or a function that receives and returns it. Use it for ECharts settings no prop covers.
themeThemeInputA theme, or a partial set of tokens merged over the surrounding theme, for this chart only.
modeModeInput"auto" (default) follows the page, "system" follows the OS, or force "light" / "dark".
rendererRendererInput"auto" (default) uses SVG for light charts and canvas for heavy ones.
animatebooleanSet false to disable animation. Reduced-motion preferences are always respected.
lazybooleanMount the chart only when it scrolls near the viewport. Default true.
groupstringLink tooltips with other charts sharing this group id.
exportableboolean | ExportFormat[]Show an export menu: true or a list of formats from png, jpeg, svg, pdf, csv, json.
tablebooleanShow a collapsible "View data" table under the chart.
altstringAccessible description: the chart type and measures, then the main pattern and the notable values.
idstringStable id for this chart's selection in the shared store.
onEventsRecord<string, ChartEventHandler>ECharts event handlers, e.g. { click: (params, chart) => {} }. Prefix a name with zr: to bind to the canvas itself.
onReady(chart: EChartsInstance) => voidCalled with the ECharts instance once it is created.
classNamestringClass name for the outer <figure>.
styleCSSPropertiesInline style for the outer <figure>.