Skip to main content
Histogram takes a list of raw numeric values, groups them into bins, and renders the result as a bar chart. Where a bar chart compares named categories, a histogram answers a different question: “how is this data distributed?” You give it numbers, it figures out the ranges and counts. All the binning math happens in Python at construction time — the renderer receives a standard BarChart payload, so there’s no new component to learn on the wire.

​
Basic Usage

Pass a list of numbers and Histogram divides them into 10 equal-width bins by default. Each bar represents a range, and its height shows how many values fall within that range. The shape of the resulting chart immediately reveals the distribution: a tall cluster on the left with a long tail to the right suggests most values are fast, but some outliers are significantly slower.

​
Custom Bin Count

Set bins to control how many equal-width buckets the data is split into. Fewer bins give a coarser, smoother view of the distribution that emphasizes the overall shape. More bins reveal finer detail — individual peaks and valleys — but can make the chart noisy if your dataset is small. A good rule of thumb: start with the default 10 and adjust based on what story the data is telling.

​
Explicit Bin Edges

When you need precise control over where bins start and end, pass bin_edges instead. The list defines the boundaries between bins — three edges produce two bins, four edges produce three, and so on. Values outside the edge range are excluded. This is useful when your domain has meaningful thresholds. For API response times, you might define bins around SLA boundaries: “under 100ms” (fast), “100-200ms” (acceptable), “200-300ms” (slow), and “over 300ms” (investigate). The unequal bin widths tell a story that equal-width bins would miss.

​
Styled

Customize the bar color with any CSS color string and adjust the chart height. The color parameter applies to all bars uniformly — since histograms represent a single variable’s distribution, one color is the norm.

​
API Reference

Histogram Parameters

​
values
list[int | float]
required
Raw numeric values to bin.
​
bins
int
default:"10"
Number of equal-width bins. Ignored when bin_edges is set.
​
bin_edges
list[float] | None
default:"None"
Explicit bin boundaries. Overrides bins when provided.
​
color
str | None
default:"None"
Bar fill color as a CSS color string.
​
height
int
default:"300"
Chart height in pixels.
​
bar_radius
int
default:"4"
Corner radius of each bar in pixels.
​
show_tooltip
bool
default:"True"
Show tooltips on hover.
​
show_legend
bool
default:"False"
Show a legend below the chart.
​
show_grid
bool
default:"True"
Show horizontal grid lines.
​
css_class
str | None
default:"None"
Additional Tailwind CSS classes.

​
Protocol Reference

Histogram
{
  "type": "BarChart",
  "values": "array (required)",
  "bins?": 10,
  "bin_edges?": "Action[]",
  "data?": "array",
  "series?": "[ChartSeries]",
  "xAxis?": "string",
  "height?": "300",
  "showTooltip?": true,
  "showLegend?": false,
  "showGrid?": true,
  "color?": "string",
  "barRadius?": 4,
  "cssClass?": "string"
}