Histogram & Density

Demo & usage

More examples

When to use

• Seeing the SHAPE of one numeric variable — where the mass sits, whether it is skewed, whether it has two modes.
• Answering "what share came in under X" with the cumulative measure.
• For comparing distributions across several groups, a Box Plot puts them side by side; for individual points, a Scatter Plot.

Async states

• loading
• empty
• error
• retry

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `samples`, `loading` and `error`.
• Set `filtered` when a search or filter is active. It is the difference between "you have no orders" and "no orders match this filter" — telling a customer with 4,000 orders the first one reads as a bug.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Five bin-width rules, or explicit edges of your own — an edge is widened rather than lose a sample outside it, because a count that does not add up is the one thing a histogram must never do. Repeated edges are merged; an edge list with fewer than two distinct numbers falls back to the bin rule, and the note under the plot says so rather than showing an empty chart.
• Count, density or cumulative measures.
• Optional kernel density overlay with a bandwidth override — weighted the same way as the bars when the samples carry weights — and an optional rug of individual readings.
• Statistical annotation: `showMean`, `showMedian` and `quantiles` (probabilities, e.g. `[0.9, 0.99]`) draw labelled reference lines, weighted like the bars. Off by default.
• Bar colour, plot size, and a unit label carried into the axis and the table.

Best practices

• Do: Treat the bin rule as part of the finding, not a display setting. The same samples at 8 bins and at 60 are a smooth mound and a spiky comb, and neither is wrong — which is why the rule is named under every plot and cannot be hidden. Quote it when you quote the shape.
• Do: Use the density measure whenever the bins are not all the same width. Bar AREA is what a reader takes off a histogram, so drawing counts on unequal bins makes a wider bin look fuller for the same number of samples. The chart says so when you do it; density is the fix it names.
• Don't: Do not read the density curve as data. It is a kernel density estimate — a model — and its bandwidth smooths a genuinely bimodal distribution into one mound as easily as it reveals one. It is drawn dashed for that reason, and its bandwidth is stated.
• Tip: Freedman–Diaconis is the default because it scales with the interquartile range rather than the full spread, so a single extreme reading does not widen every bin. It falls back to the square-root rule when the interquartile range is zero, which a heavily-moded sample produces — and the note under the plot then names the rule that actually ran and why, not the one you asked for.

Accessibility

• Every bar is a focusable `role="button"` named with its range, count and share. Bar height is the only place a count exists in the drawing and no axis is precise enough to read one off, so those figures are in the name rather than left to be estimated.
• The plot is ONE tab stop: Tab lands on a bar, the arrow keys walk the others (Home / End jump to the ends, no wrap), Enter or Space selects. A tab stop per bar was up to 200 Tab presses to get past one chart.
• Mean, median and quantile markers are told apart by dash pattern and label, never by colour alone, and every marked figure is stated in the chart's accessible name.
• `sv-data-summary-table` publishes every bin's range, count, share and running total — the last of which the plain measure never draws at all.
• The rug is deliberately not focusable: every reading it marks is already counted in a bar that is, so making each tick a tab stop would add hundreds of stops that say nothing new.
• What shaped the picture is stated in the rendered output: the bin rule that actually ran (including a fallback, or your own edges), the sample count, unequal widths drawn at count, the density bandwidth, and any reading that could not be binned or whose weight could not be used.