import { Histogram } from "semiotic"
Histogram shows the frequency distribution of numeric data within categories by binning values and displaying bar heights proportional to count. Pass raw data points and the component handles the binning automatically. Use bins to control resolution andrelative to normalize per-category for comparison.
Quick Start
A histogram requires just data — provide multiple data points per category and the component bins them automatically.
import { Histogram } from "semiotic" const frameProps = { /* --- Data --- */ data: [ { category: "Morning", value: 62 }, { category: "Morning", value: 58 }, { category: "Morning", value: 71 }, // ...multiple data points per category { category: "Afternoon", value: 78 }, { category: "Afternoon", value: 85 }, // ...more data points ], /* --- Process --- */ valueAccessor: "value", categoryAccessor: "category", /* --- Customize --- */ categoryLabel: "Time of Day", valueLabel: "Frequency" } export default () => { return <Histogram {...frameProps} /> }
Examples
Fewer Bins
Reduce the bins count to see a coarser distribution.
import { Histogram } from "semiotic" const frameProps = { /* --- Data --- */ data: responseTimeData, /* --- Process --- */ valueAccessor: "value", categoryAccessor: "category", bins: 8, /* --- Customize --- */ categoryLabel: "Time of Day", valueLabel: "Frequency" } export default () => { return <Histogram {...frameProps} /> }
Relative Frequency
Set relative to true to normalize bin counts per category, making it easier to compare distributions with different sample sizes.
import { Histogram } from "semiotic" const frameProps = { /* --- Data --- */ data: responseTimeData, /* --- Layout --- */ relative: true, /* --- Process --- */ valueAccessor: "value", categoryAccessor: "category", /* --- Customize --- */ categoryLabel: "Time of Day", valueLabel: "Relative Frequency" } export default () => { return <Histogram {...frameProps} /> }
Colored by Category
Use colorBy to give each histogram a distinct color based on a data field.
import { Histogram } from "semiotic" const frameProps = { /* --- Data --- */ data: [ { category: "Region A", value: 120, zone: "Urban" }, { category: "Region A", value: 135, zone: "Urban" }, // ...data with zone field for coloring ], /* --- Process --- */ valueAccessor: "value", categoryAccessor: "category", /* --- Customize --- */ colorBy: "zone", categoryLabel: "Region", valueLabel: "Frequency" } export default () => { return <Histogram {...frameProps} /> }
Brush + Zoom
Enable brush on an overview to select a value range, then pass it as frameProps.rExtent to a detail chart to zoom in.
Drag to select a value range
Detail view (brush above to zoom)
JSX
const [extent, setExtent] = useState(null) <Histogram data={data} brush onBrush={setExtent} height={160} /> <Histogram data={data} frameProps={extent ? { rExtent: extent.r } : undefined} height={250} />
Props
| Prop | Type | Required | Default | Description |
|---|
data | array | Yes | — | Array of data points. Multiple points per category are binned to show frequency distribution. |
categoryAccessor | string | function | — | "category" | Field name or function to access category values. |
valueAccessor | string | function | — | "value" | Field name or function to access numeric values. |
orientation | "horizontal" | — | "horizontal" | Histograms are always horizontal. This prop is ignored. |
bins | number | — | 25 | Number of bins for the histogram. |
relative | boolean | — | false | Normalize counts per category to show relative frequency instead of absolute counts. |
categoryLabel | string | — | — | Label for the category axis. |
valueLabel | string | — | — | Label for the value axis. |
valueFormat | function | — | — | Format function for value axis tick labels. |
colorBy | string | function | — | — | Field name or function to determine histogram bar color. |
colorScheme | string | array | — | "category10" | Color scheme name or custom colors array. |
categoryPadding | number | — | 20 | Padding between categories in pixels. |
enableHover | boolean | — | true | Enable hover annotations showing bin details. |
showGrid | boolean | — | false | Show background grid lines. |
showLegend | boolean | — | true (when colorBy set) | Show a legend. Defaults to true when colorBy is specified. |
tooltip | object | function | — | — | Tooltip configuration or render function. |
width | number | — | 600 | Chart width in pixels. |
height | number | — | 400 | Chart height in pixels. |
margin | object | — | { top: 50, bottom: 60, left: 70, right: 40 } | Margin around the chart area. |
title | string | — | — | Chart title displayed at the top. |
brush | boolean | — | — | Enable value-axis brush selection. |
onBrush | function | — | — | Callback with { r: [min, max] } or null when brush clears. |
linkedBrush | string | object | — | — | LinkedCharts brush integration name. |
frameProps | object | — | — | Additional StreamOrdinalFrame props for advanced customization. Escape hatch to the full Frame API. |
Graduating to the Frame
When you need more control — custom bin rendering, overlaid annotations, mixed summary types — graduate toStreamOrdinalFrame directly.
Chart (simple)
JSX
import { Histogram } from "semiotic" <Histogram data={responseTimeData} categoryAccessor="category" valueAccessor="value" bins={15} categoryLabel="Time of Day" valueLabel="Frequency" />
Frame (full control)
JSX
import { StreamOrdinalFrame } from "semiotic" <StreamOrdinalFrame data={responseTimeData} oAccessor="category" rAccessor="value" summaryType={{ type: "histogram", bins: 15 }} summaryStyle={d => ({ fill: "#6366f1", stroke: "#6366f1", fillOpacity: 0.8 })} oPadding={20} axes={[ { orient: "left", label: "Frequency" }, { orient: "bottom", label: "Time of Day" } ]} summaryHoverAnnotation={true} size={[600, 400]} margin={{ top: 50, bottom: 60, left: 70, right: 40 }} />
- ViolinPlot — smooth density estimation instead of discrete bins
- BoxPlot — summary statistics (median, quartiles) per category
- BarChart — for aggregated category comparisons
- StreamOrdinalFrame — the underlying Frame with full control over every rendering detail