histplot¶

`histplot(data, *, x=None, y=None, hue=None, hue_order=None, stat='count', bins=10, binwidth=None, binrange=None, discrete=False, color=None, palette=None)` ¶

Plot a histogram of a numeric variable.

Bins must be equal-width — Mermaid places bars equidistantly, so unequal bin widths would misrepresent the data and are rejected.

Parameters:

Name	Type	Description	Default
`data`	`IntoFrame`	Input data. Any narwhals-compatible DataFrame or LazyFrame.	required
`x`	`str \| None`	Column name for horizontal distribution (mutually exclusive with `y`).	`None`
`y`	`str \| None`	Column name for vertical distribution (mutually exclusive with `x`).	`None`
`hue`	`str \| None`	Column name for grouping into separate series.	`None`
`hue_order`	`list \| None`	Explicit order for hue levels.	`None`
`stat`	`str`	Statistic to plot. One of `"count"`, `"frequency"`, `"probability"`, `"proportion"`, `"percent"`, `"density"`.	`'count'`
`bins`	`int \| list`	Number of equal-width bins, or an explicit list of bin edges.	`10`
`binwidth`	`float \| None`	Width of each bin. Overrides `bins` if provided.	`None`
`binrange`	`tuple \| None`	`(min, max)` tuple clamping the data range.	`None`
`discrete`	`bool`	If `True`, treat each unique integer value as its own bin.	`False`
`color`	`str \| None`	Single colour for all bars (CSS colour string).	`None`
`palette`	`list \| None`	List of colours, one per hue level.	`None`

Returns:

Name	Type	Description
`XYChart`	`XYChart`	An instance ready to render or further configure.

Raises:

Type	Description
`ValueError`	If neither or both of `x`/`y` are provided, if `stat` is invalid, or if explicit bin edges are not equally spaced.