Charts - Histogram

#Usage

import {
    ChartAnnotation,
    ChartCanvas,
    ChartCaption,
    ChartDataLabels,
    ChartHistogram,
    ChartHover,
    ChartItem,
    ChartLegend,
    ChartNavigator,
    ChartOverlap,
    ChartReferenceLine,
    ChartStacked,
    ChartSvg,
    ChartTitle,
    ChartTooltip,
    ChartXAxis,
    ChartYAxis,
    ChartZoom
} from '@primeui/vue-chart';

<ChartSvg>
    <!-- or <ChartCanvas> -->
    <ChartHistogram :data="data" bin-x-field="binXField" :bins="10" />
    <ChartXAxis />
    <ChartYAxis />
</ChartSvg>

A histogram takes raw observations rather than aggregated rows and groups them into bins, drawing one bar per bin. Each bar spans a range on the independent axis, so bar width carries data rather than presentation. Binning happens before layout, which means the rest of the cartesian pipeline treats the result as bars: axes, tooltips, legends, zoom, and annotations all behave as they do for ChartBar.

#Basic

Bind raw observations with binXField and nothing else. The bins are derived with the square-root rule, and each bar counts the observations whose value falls in its range.

#Bin Rules

bins takes a number to set the count outright, or a named rule that derives it from the number of observations: 'square-root' (the default), 'sturges', or 'rice'. A rule keeps the count proportionate as the data grows, where a fixed number does not.

#Explicit Edges

Pass an array of N+1 boundaries to control every bin. Ranges do not need equal width, and each bar is drawn at the width of its own range, so an unequal set stays truthful.

#Bin Width

binWidth sets the range of each bin in data units and takes precedence over bins. The final bin extends past the largest observation when the span does not divide evenly.

#Reduce

By default each bar is a count of its members. Bind a measure with valueYField and set reduce to 'sum', 'mean', 'min', or 'max' to aggregate that measure instead.

#Negative Values

A reduced measure can resolve below zero, and those bars extend downward from the baseline. Counting never produces a negative bar, so this applies only when reduce aggregates a signed measure.

#Colors

Pass an array to color for a custom palette. Bars cycle through the colors by bin index. A function receives each bin and returns a color string for per-bin control.

#Gradient Color

color also accepts a gradient definition. Linear and radial gradients both work, in SVG and Canvas.

#Grouped

Multiple ChartHistogram components render side by side within each bin. Bin edges are pooled across every series, so the bars line up and stay comparable.

#Stacked

Wrap the series in ChartStacked to stack bins on top of each other. Edges are pooled here as well, since stacking needs a shared base.

#Overlap

Wrap the series in ChartOverlap to layer distributions at the same position. Each series keeps its own bins unless the same bins value is passed to both, and overlaid fills are softened so the layers remain readable. Bars are not narrowed here, because a histogram's width is its bin.

#Horizontal

Bind binYField instead of binXField to run the bins down the Y axis. The measure then lands on X. There is no orientation prop.

#Custom Shape

renderShape replaces the default rectangle. It receives the computed geometry and returns an SVG path d string, which works in both SVG and Canvas.

#Border

Border props match ChartBar. Bins sit 1px apart by default, so a border outlines each range rather than fusing the series into one silhouette.

#Bin Sizing

categoryGap widens the gap between bins beyond the 1px default, and maxBarThickness caps how wide a bar may become. Both are presentation props: barThickness and maxBarThickness override the bin's own width, which misreports unequal bins.

#Declarative

Use ChartItem children instead of a data array. Each item is one observation bound with binX or binY, not one bar. This suits small or illustrative sets; a data array is better for large ones.

#Title & Caption

Add ChartTitle and ChartCaption for a heading and a source note.

#Hover

Add ChartHover to enable hover styling. hoverColor sets a per-bin fill that short-circuits the global brightness cascade.

#Tooltip

ChartTooltip reports the bin range alongside the bar value, so the boundaries of each range stay visible.

#Legend

ChartLegend lists each series by name. Toggling a series rescales the axis while the pooled bin edges stay fixed, so the remaining bars keep their position.

#Axes

Bind yAxisId to put series on separate value axes. The independent axis stays continuous, since bins are ranges rather than categories.

#Data Labels

ChartDataLabels draws the reduced value on each bin.

#Zoom & Navigator

ChartZoom and ChartNavigator work on the binned axis. Bins are derived once from the full dataset, so zooming moves the viewport rather than re-binning.

#Annotation

ChartAnnotation draws custom content over the plot area. The SVG renderer takes a template, and the Canvas renderer takes a render callback that receives the drawing context.

#Reference Lines & Bands

ChartReferenceLine marks a threshold on either axis, which suits service levels and distribution targets.

#Null Values

Observations that are not finite numbers are dropped before binning, including null, undefined, and NaN. No bin is created for them and no gap appears in the axis, since a histogram has no slot reserved per row. Counts therefore reflect the finite observations only. There is no connectNulls prop, because there is no category slot to preserve.

#Decimation

ChartDecimation does not apply to histograms. A histogram's rows are its bins, so dropping rows would discard whole ranges and lose the observations they hold. Bins are capped by the bins or binWidth props instead.

#Animation

Pass the chart-root animation prop to control entrance and update transitions. Bins keep their identity across updates while the edges stay fixed, so bars grow in place rather than snapping.

For full configuration see Animation.

#Export

Add ChartExportMenu to let users download the chart as PNG, SVG, or PDF.

See Export for format options and programmatic export.

#Responsive

See Responsive for container sizing, aspect ratio, and breakpoint configuration.

#Accessibility

See Accessibility for ARIA labels, keyboard navigation, and screen reader support.

#API

#ChartHistogram

Visual styling props with type accessor → R accept a static value, a per-item array, a field name (keyof T), or a callback (ctx: ItemContext<T>) => R | undefined. Color-family arrays cycle modulo length; other accessor arrays clip and fall back to the series default.

#Bin

The datum passed to every accessor callback is a bin rather than an original row.

#ChartItem

Use ChartItem as children of ChartHistogram instead of a data array. Each item is one observation.

#ChartStacked

Wrap ChartHistogram children inside ChartStacked to stack bins. Without this wrapper, multiple histograms render as grouped side-by-side bars.

#ChartOverlap

Wrap multiple ChartHistogram components inside ChartOverlap to layer them at the same position. No configuration required. Each series keeps its own bins by default; passing the same bins value to every series makes them comparable.

#Related Docs

• Column & Bar
• Legend
• Tooltip
• Hover
• Data Labels
• Annotation
• Zoom & Pan
• Navigator
• Reference Lines & Bands
• Animation
• Axes