# Histogram

> Histogram with automatic (Freedman–Diaconis / Sturges) or fixed bins, counts or densities, and an optional fitted normal curve.

Source: https://ui.jcsoftdev.com/docs/components/histogram

Histogram with automatic (Freedman–Diaconis / Sturges) or fixed bins,
counts or densities, and an optional fitted normal curve. Hovering or
arrowing through the bins shows their range and counts.

## Import

```ts
import { Histogram } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/histogram`.

## Usage

```tsx
<Histogram
  title="Distribución del ticket de octubre"
  series={[{ id: "ticket", name: "Ticket", values: tickets }]}
  bins="auto"
  mode="count"
  normalCurve={false}
  valueFormat="currency"
  xAxis={{ title: "Ticket (S/)" }}
  height={300}
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` * | `string` |  |  |
| `series` * | `readonly HistogramSeries[]` |  | One or more samples binned on the same edges; several series overlap. |
| `bins` | `number \| BinRule` | `"auto"` | Bin rule or approximate count. `auto` = Freedman–Diaconis (Sturges when the IQR is 0). |
| `binWidth` | `number` |  | Exact bin width in data units; wins over `bins`. |
| `domain` | `readonly [number, number]` |  | Range to bin; the data range by default. |
| `mode` | `"count" \| "density"` | `"count"` | "count": observations per bin. "density": count / (n · width), area 1. |
| `normalCurve` | `boolean` | `false` | Overlay the normal curve fitted to each series (same mean and standard deviation). |
| `valueFormat` | `ValueFormat` |  | Format of the binned values (x axis, tooltip ranges). |
| `xAxis` | `DistributionAxisOptions` |  |  |
| `yAxis` | `DistributionAxisOptions` |  |  |
| `exploded` | `boolean` |  | Explode every bin into one dot per observation (a dot plot on the same bins). Controlled when set; otherwise `defaultExploded` starts it. |
| `defaultExploded` | `boolean` | `false` |  |
| `onExplodedChange` | `((exploded: boolean) => void)` |  |  |
| `explodeToggle` | `boolean` | `false` | Shows the toggle button under the plot. |
| `height` | `number \| "fill"` | `300` |  |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the drawing from the container width when `height` is not "fill". |
| `legend` | `boolean \| "top" \| "bottom"` |  |  |
| `grid` | `boolean` | `true` |  |
| `tooltip` | `boolean` | `true` |  |
| `loading` | `boolean` |  |  |
| `animate` | `boolean` | `true` |  |
| `labels` | `Partial<DistributionLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-histogram--default)
- [Fixed Bin Width](/storybook/?path=/story/charts-histogram--fixed-bin-width)
- [Density With Normal Curve](/storybook/?path=/story/charts-histogram--density-with-normal-curve)
- [Sturges](/storybook/?path=/story/charts-histogram--sturges)
- [Overlaid Series](/storybook/?path=/story/charts-histogram--overlaid-series)
- [Explode](/storybook/?path=/story/charts-histogram--explode)
- [Narrow](/storybook/?path=/story/charts-histogram--narrow)
- [Loading](/storybook/?path=/story/charts-histogram--loading)
- [Empty](/storybook/?path=/story/charts-histogram--empty)

## Source

`packages/ui/src/charts/histogram/histogram.tsx`