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
Rows are raw observations with a category, the same data a box plot takes. The chart builds each profile from them.
<script setup lang="ts">
import {
Grid,
Violin,
ViolinChart,
ViolinTooltip,
ViolinXAxis,
ViolinYAxis,
} from "@/components/ui/charts";
// One row per page load.
const data = [
{ ms: 820, region: "US East" },
{ ms: 940, region: "US East" },
{ ms: 1310, region: "US East" },
{ ms: 760, region: "US East" },
{ ms: 1020, region: "EU West" },
{ ms: 1180, region: "EU West" },
{ ms: 2240, region: "EU West" },
{ ms: 980, region: "EU West" },
];
const formatMs = (value: number) => `${value} ms`;
</script>
<template>
<ViolinChart
ariaLabel="Page load time by region"
category-key="region"
:data="data"
>
<Grid horizontal />
<Violin data-key="ms" label="Page load" />
<ViolinXAxis />
<ViolinYAxis :format-value="formatMs" />
<ViolinTooltip />
</ViolinChart>
</template>Anatomy
The same parts as the box plot, with Violin in place of BoxPlot. Each violin is a density profile mirrored around its category's center line.
<ViolinChart category-key="region" :data="data">
<Grid horizontal />
<Violin data-key="ms" fill="var(--chart-1)" label="Page load" />
<ViolinXAxis />
<ViolinYAxis />
<ViolinTooltip />
</ViolinChart>ViolinChart: Groups the rows bycategoryKeyand builds each profile frombinscounts.Grid: Guide lines along the value axis.Violin: One series: a violin per category, with its range, middle half and median inside.ViolinXAxis: Categories on a vertical chart, values on a horizontal one.ViolinYAxis: Values on a vertical chart, categories on a horizontal one.ViolinTooltip: Median, middle half, range and count for the hovered category.
Shape and width
Each profile counts the values in bins slices of the range (28 by default), smooths the counts, then scales the result so it peaks at violinWidth of its slot (0.9). Fewer bins give a softer outline, more bins show detail but get jagged on small samples.
Because every violin is scaled to its own peak, widths compare shapes, not counts. The tooltip has the counts.
Horizontal violins
Set orientation="horizontal" to list the categories down the side, with the values along the bottom. Use <Grid vertical /> so the guides follow the values.
Two series per category
Add a second Violin and the series share each category's band, side by side. With more than one series, the tooltip lists each one's median.
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.
The tooltip's content gets the hovered category and a series array of summaries with min, q1, median, q3, max and count. Return TooltipContent to keep the panel's look with your own rows.
Set :showBox="false" on a Violin to drop the bar, the range line and the median dot from inside it.
<ViolinTooltip>
<template #content="{ point }">
<TooltipContent
:rows="point.series.map((series) => ({
color: series.color,
label: `${series.label} median`,
value: `${series.median} ms`,
}))"
:title="point.category"
/>
</template>
</ViolinTooltip>Where a part renders content of its own, you pass it in. In Vue:
ViolinTooltip:<template #content="{ point, index }">
Loading state
While status is "loading", the chart draws a skeleton violin for each category (four with no data) and ignores the pointer. loadingLabel adds text over it. On "ready" the real violins open out.
<ViolinChartLoading /> stands in for a chart with no rows yet. It takes orientation and label.
Animation
Violins open out from their center lines over animationDuration (1100 ms), one category after another. :animate="false" on the Violin draws them in place.
Changed data morphs each outline into its new shape over 500 ms. Reduced motion skips the entrance and the morph.
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.
fill colors the violin. The bar, line and dot inside it are drawn in --chart-background, so they read against any fill.
| 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-background | --card | dot halos, the gaps between stacked marks |
--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-background: var(--background);
--chart-grid: var(--muted);
}Accessibility
The chart is an image named by ariaLabel ("Violin plot" by default). A violin's shape is hard to put in words, so say what it shows in ariaDescription, such as which category has the longest tail.
- Tab
- Moves focus to the chart and shows the first category.
- Arrow Right
- Moves to the next category. ArrowDown does the same.
- Arrow Left
- Moves to the previous category. ArrowUp does the same.
- Home
- Jumps to the first category.
- End
- Jumps to the last category.
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).
ViolinChart
categoryKeystring
Key of the column naming each row's category: one violin per category (per series), in first-seen order.
orientation?"vertical" | "horizontal"
"vertical": categories along the bottom, values up the side. "horizontal": categories down the side, values along the bottom.
- Type
"vertical" | "horizontal"- Default
"vertical"
domain?readonly [number, number]
The value axis range [min, max]. Defaults to the observations' extent, rounded to nice values.
bins?number
How many bins the density profiles are counted in across the value range (each then smoothed and scaled to its peak).
- Default
28
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.
Violin
violinWidth?number
Width of a violin at its peak as a share of its category's band, from 0 to 1.
- Default
0.9
showBox?boolean
Draw the quartile bar, the range line and the median dot inside each violin.
- Default
true
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
ViolinXAxis
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
ViolinYAxis
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
ViolinTooltip
#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
ViolinChartLoading
orientation?"vertical" | "horizontal"
"vertical": the skeleton's categories along the bottom. "horizontal": down the side. Defaults to the chart's own default.
- Type
"vertical" | "horizontal"
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.
