histogram

Configuration Structure

histogram: {
  bins: 'auto' | 'fd' | ...,
  binWidth: number,
  range: number[],
  normalize: 'count' | 'relative' | ...,
  cumulative: boolean,
  overlap: boolean,
}

plotOptions

chart.type: 'histogram'. The series carry raw observations, a flat number array or { y } objects, and are binned into one column per bin. All series share one set of edges, so overlaid distributions stay comparable.

Requires the optional stats feature: import from apexcharts/histogram, or add import 'apexcharts/features/stats' alongside apexcharts/bar. The default apexcharts bundle already includes it. Without it the chart warns and draws nothing, rather than rendering one bar per observation.

bins

Default: 'auto'

How the bin width is chosen: the name of a rule, or a fixed bin count.

Available Options:

  • 'auto' (default): the narrower of Freedman-Diaconis and Sturges, falling back to Sturges when the IQR is 0.
  • 'fd': Freedman-Diaconis. Derived from the IQR, so it resists outliers.
  • 'sturges': Sturges. Assumes roughly normal data and under-bins large samples.
  • 'scott': Scott. Derived from the standard deviation.
  • 'rice': Rice. A cube-root rule.
  • 'sqrt': the square root of the observation count.
  • Number: that many bins, regardless of the data.

Ignored when binWidth is set.

binWidth

Default: undefined

Explicit bin width in value units. Wins over bins, for when the boundaries carry meaning of their own, decades or 5-minute buckets, rather than being a statistical choice.

range

Default: undefined

[min, max] to bin over instead of the data's own extent. Use it to hold several histograms on one scale when their samples do not span the same values.

normalize

Default: 'count'

The units of the bar heights.

Available Options:

  • 'count' (default): observations per bin.
  • 'relative': percent of that series' total. This is what makes samples of different sizes comparable.
  • 'density': count / (n * binWidth), so the total area is 1. Keeps bins of different widths comparable, and matches the scale a violin chart draws on.

cumulative

Default: false

Running total across the bins, i.e. a cumulative distribution.

Available Options:

  • true
  • false (default)

overlap

Default: true

With more than one series, draw every distribution across the full bin so they overlay, instead of dividing the bin between them.

All series already share one set of edges, and comparing two shapes is the reason to put them on one axis, so this defaults to true. Splitting the bin makes the columns stop touching, which reads as a clustered bar chart rather than as two distributions.

An overlay also softens the fill and drops the bin separator stroke so the overlapping region reads. Both remain overridable through fill and stroke.

A single series is unaffected either way.

Available Options:

  • true (default)
  • false: side-by-side bars within each bin.