shadcn.io is an independent project built on shadcn/ui
Installation
The command adds the example above to components/charts/ and, the first time, the chart kit to components/ui/charts/. Both are source files in your project from then on: read them, change them, delete what you don't use.
Usage
Pass the raw observations, one row each. The chart counts them into bins itself, so there's nothing to aggregate first.
<script setup lang="ts">
import {
Grid,
Histogram,
HistogramChart,
HistogramTooltip,
HistogramXAxis,
HistogramYAxis,
} from "@/components/ui/charts";
// One row per request, in milliseconds.
const data = [
{ ms: 182 }, { ms: 240 }, { ms: 198 }, { ms: 311 }, { ms: 205 },
{ ms: 264 }, { ms: 189 }, { ms: 422 }, { ms: 231 }, { ms: 217 },
{ ms: 176 }, { ms: 293 }, { ms: 208 }, { ms: 356 }, { ms: 221 },
];
const formatMs = (value: number) => `${value} ms`;
</script>
<template>
<HistogramChart ariaLabel="Checkout response times" :data="data">
<Grid horizontal />
<Histogram data-key="ms" label="Requests" />
<HistogramXAxis :format-value="formatMs" />
<HistogramYAxis />
<HistogramTooltip />
</HistogramChart>
</template>Anatomy
HistogramChart does the binning. Each Histogram inside it reads one numeric column, and the rest is optional.
<HistogramChart :data="data" :thresholds="24">
<Grid horizontal />
<Histogram data-key="before" fill="var(--chart-3)" label="Before" />
<Histogram data-key="after" fill="var(--chart-1)" label="After" />
<HistogramXAxis />
<HistogramYAxis />
<HistogramTooltip />
</HistogramChart>HistogramChart: Bins every series on the same thresholds and lays out the plot.Grid: Dashed guide lines behind the bars.Histogram: One series: the column named bydataKey, counted per bin.HistogramXAxis: The binned values along the bottom.HistogramYAxis: Counts up the side.HistogramTooltip: The hovered bin's range and each series' count.
Choosing the bins
Without thresholds, the bin count follows Sturges' rule on the number of rows. Pass a number for roughly that many bins, with edges rounded to clean values, or an array for the exact edges.
domain fixes the range that gets binned, and rows outside it are left out. If you pass edges as well, domain has to match the first and last one, or the chart throws an error.
Overlapping series
Add a second Histogram and both series are binned on the same edges. Where they overlap, the bars are drawn at 55% opacity so one shows through the other. Set fillOpacity to change that.
Wrap the chart in ChartLegendHoverProvider with a ChartLegend, and hovering a legend row fades the other series.
Stacked series
Add stacked to the chart and each bin's bars stack, in the order you write the series. Only the top segment keeps its rounded corners, and the y axis scales to the tallest stack.
Customization
The kit is in your project, in components/ui/charts/: your framework's components over a shared core/. Change a default there and every chart picks it up.
class goes on the chart's container, so size and spacing are utility classes.
To write the tooltip yourself, pass content. It gets the bin as point, with its edges x0 and x1, the total and a series array of counts. Return TooltipContent to keep the default panel's look.
On a Histogram, radius rounds the bar tops (4 px) and fadedOpacity sets how far the other bins dim while one is hovered (0.3).
<HistogramTooltip>
<template #content="{ point }">
<TooltipContent
:rows="[
{ color: 'var(--chart-1)', label: 'Requests', value: point.total },
]"
:title="`${point.x0} to ${point.x1} ms`"
/>
</template>
</HistogramTooltip>Where a part renders content of its own, you pass it in. In Vue:
HistogramTooltip:<template #content="{ point, index }">
Loading state
Pass status="loading" while the rows are on their way. The bars give way to a shimmering skeleton of bins, the pointer is ignored, and loadingLabel puts a short line of text over it. On "ready" the real bins grow in on the same chart.
With no data to pass yet, render <HistogramChartLoading /> in the chart's place. Give it the chart's aspectRatio so nothing shifts when the data arrives.
Animation
Bins grow up from the baseline, left to right, over animationDuration (1100 ms). With a single series, :animate="false" on the Histogram draws the bars at full height from the start.
New data doesn't replay the entrance: the bars glide to their new heights over 500 ms. Reduced motion turns off both.
Theming
Every color in the kit is one of your theme's tokens or a mix of them, except --chart-positive, a fixed green. A preset or the .dark class restyles the chart, and overriding a token in your CSS changes it everywhere.
Each Histogram takes its color as fill. Without one, series take --chart-1 to --chart-5 in the order you write them.
| Token | Default | Paints |
|---|---|---|
--chart-1 | your theme's | the first series |
--chart-2 | your theme's | the second series |
--chart-3 | your theme's | the third series |
--chart-grid | --border | grid lines |
--chart-label | --muted-foreground | tick labels |
--chart-foreground-muted | --muted-foreground mixed toward --background | skeletons and faded marks |
--chart-tooltip-background | --popover | the tooltip panel |
:root {
--chart-grid: var(--muted);
--chart-label: var(--foreground);
}Accessibility
The chart is an image named by ariaLabel ("Histogram" by default). The point of a histogram is usually a number, such as the median or how many requests ran over a budget, so put it in ariaDescription.
- Tab
- Moves focus to the chart and shows the first bin.
- Arrow Right
- Moves to the next bin. ArrowDown does the same.
- Arrow Left
- Moves to the previous bin. ArrowUp does the same.
- Home
- Jumps to the first bin.
- End
- Jumps to the last bin.
API reference
Vue takes the same props as React, in camelCase or kebab-case, with class for className. Render props are scoped slots (#content), and callbacks such as onHoverChange can be written as listeners (@hover-change).
HistogramChart
thresholds?number | readonly number[]
The bins: a target bin count (the boundaries are rounded to nice values) or the exact bin boundaries, in order. Defaults to Sturges' rule on the number of observations.
- Type
number | readonly number[]
domain?readonly [number, number]
The binned range [min, max]. Defaults to the observations' extent.
stacked?boolean
Stack the series' bars in each bin. Otherwise they overlap, each translucent.
- Default
false
datareadonly DistributionRow[]
The observations, one object per row. Each series reads its dataKey column; rows without a finite number there are skipped.
aspectRatio?string
Width to height ratio of the chart, for example "2 / 1" or "16 / 9".
- Default
"2 / 1"
margin?Partial<ChartMargin>
Space around the plot in pixels, per side. Each side defaults to fit the chart's axes.
- Type
Partial<ChartMargin>
animationDuration?number
Duration of the entrance in milliseconds.
- Default
1100
ariaLabel?string
Accessible name of the chart. Defaults to its kind, for example "Histogram" or "Box plot".
ariaDescription?string
Accessible description of the chart.
status?ChartStatus
"loading" draws a shimmering skeleton shaped like the chart in place of its marks and ignores the pointer; switching to "ready" plays the entrance. Switching back to "loading" fades the marks out first.
- Default
"ready"
loadingLabel?string
Text shown centered over the plot, with a shimmer, while status is "loading". Nothing is shown when it is unset or empty.
class?string
Class names added to the chart's container.
style?CSSProperties
Inline styles for the chart's container.
children?ReactNode
The chart's parts: its series, Grid, axes and tooltip.
Histogram
radius?number
Radius of each bar's top corners in pixels.
- Default
4
fillOpacity?number
Opacity of the bars' fill. Defaults to 1, or 0.55 when several series overlap.
dataKeystring
Key of the numeric column this series reads from each row.
label?string
The series' name in the tooltip and legend. Defaults to dataKey.
fill?string
Fill colour. Defaults to the series' palette colour, var(--chart-1) for the first.
stroke?string
Outline colour. Defaults to the fill.
fadedOpacity?number
Opacity of the other items while one is hovered (and of the other series while a legend row is).
- Default
0.3
animate?boolean
Play the entrance.
- Default
true
Grid
horizontal?boolean
Show horizontal grid lines.
- Default
true
vertical?boolean
Show vertical grid lines.
- Default
false
numTicksRows?number
Number of horizontal grid lines. Ignored when rowTickValues is set.
- Default
5
numTicksColumns?number
Number of vertical grid lines.
- Default
10
rowTickValues?number[]
Explicit y values for the horizontal grid lines. Overrides numTicksRows.
stroke?string
Color of the grid lines.
- Default
"var(--chart-grid)"
loadingStroke?string
Grid color while the chart is loading. Falls back to stroke.
strokeOpacity?number
Opacity of the grid lines.
- Default
1
strokeWidth?number
Width of the grid lines in px.
- Default
1
strokeDasharray?string
Dash pattern of the grid lines.
- Default
"4,4"
highlightRowValues?number[]
Y values of horizontal lines drawn with the highlight styling, for example a zero baseline.
highlightRowStroke?string
Color of the highlighted rows.
- Default
"var(--chart-foreground-muted)"
highlightRowStrokeOpacity?number
Opacity of the highlighted rows.
- Default
1
highlightRowStrokeWidth?number
Width of the highlighted rows in px.
- Default
1
highlightRowStrokeDasharray?string
Dash pattern of the highlighted rows.
- Default
"0"
fadeHorizontal?boolean
Fade the horizontal lines toward transparent at the left and right edges.
- Default
true
fadeVertical?boolean
Fade the vertical lines toward transparent at the top and bottom edges.
- Default
false
hideHorizontalEdgeLines?boolean
Drop the first and last horizontal line (kept when two or fewer remain).
- Default
false
hideVerticalEdgeLines?boolean
Drop the first and last vertical line (kept when two or fewer remain).
- Default
false
shimmer?boolean
While the chart is loading, sweep a bright band across the grid.
- Default
false
shimmerStroke?string
Color of the shimmer band.
- Default
"color-mix(in oklch, var(--bkm-foreground) 68%, transparent)"
shimmerSpeed?number
Speed multiplier of the shimmer sweep. 2 is twice as fast.
- Default
1
HistogramXAxis
numTicks?number
Target number of tick labels on a value axis.
- Default
5
formatLargeNumbers?boolean
Abbreviate values of 1000 and above as thousands, for example 2k or 1.5k. Ignored when formatValue is set.
- Default
true
formatValue?(value: number) => string
Formats a value tick into its label, for example (value) => \${value} ms\``.
- Type
(value: number) => string
HistogramYAxis
numTicks?number
Target number of tick labels on a value axis.
- Default
5
formatLargeNumbers?boolean
Abbreviate values of 1000 and above as thousands, for example 2k or 1.5k. Ignored when formatValue is set.
- Default
true
formatValue?(value: number) => string
Formats a value tick into its label, for example (value) => \${value} ms\``.
- Type
(value: number) => string
HistogramTooltip
#content?slot: { point, index }
Replaces the default panel body (a title over one row per value) with your own content for the hovered item.
formatValue?(value: number) => string
Formats the values the default body shows. Defaults to the chart's value axis formatValue, else en-US numbers.
- Type
(value: number) => string
HistogramChartLoading
aspectRatio?string
Width to height ratio of the placeholder, for example "2 / 1".
- Default
"2 / 1"
margin?Partial<ChartMargin>
Space around the plot in pixels, per side.
- Type
Partial<ChartMargin>
label?string
Text shown centered over the skeleton, with a shimmer. Nothing is shown when it is unset or empty.
class?string
Class names added to the placeholder's container.
- Default
""
Examples
4 examples on Vue, each live with its code and its own install command.
