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 periods, oldest first: a label under xDataKey (period by default) and one number per series. A series with no value in a period sits out that period's ranking.
import {
BarXAxis,
BarYAxis,
Bump,
BumpChart,
ChartTooltip,
Grid,
} from "@/components/ui/charts";
const data = [
{ period: "Week 1", atlas: 12, comet: 18, nova: 9 },
{ period: "Week 2", atlas: 21, comet: 19, nova: 17 },
{ period: "Week 3", atlas: 25, comet: 31, nova: 28 },
{ period: "Week 4", atlas: 34, comet: 33, nova: 40 },
];
export const StandingsChart = () => (
<BumpChart ariaLabel="Team standings by week" data={data}>
<Grid vertical />
<Bump dataKey="atlas" label="Atlas" />
<Bump dataKey="comet" label="Comet" />
<Bump dataKey="nova" label="Nova" />
<BarXAxis />
<BarYAxis />
<ChartTooltip />
</BumpChart>
);Anatomy
One <Bump> per series. Each takes the next theme color unless you pass color.
<BumpChart data={data} xDataKey="year">
<Grid vertical />
<Bump dataKey="python" label="Python" />
<Bump dataKey="typescript" label="TypeScript" />
<Bump dataKey="java" label="Java" />
<BarXAxis />
<BarYAxis />
<ChartTooltip />
</BumpChart>BumpChart: Ranks each period's values and puts rank 1 at the top.Grid: A vertical line at each period.Bump: One series: a line through its ranks, a dot per period and its name at the end.BarXAxis: The period labels.BarYAxis: The ranks, written#1,#2unless you passformatValue.ChartTooltip: The hovered series' rank and value in every period.
Which way to rank
By default the largest value ranks first. Set rankBy="ascending" when smaller is better, as with a response time or a price, or rankBy="none" when your data already holds ranks.
Ties keep the order you wrote the <Bump> elements in.
Names or a legend
Each line ends with its series' name in the line's color, and the right margin widens to fit the longest one. With many series or long names, pass showLabels={false} and put a <ChartLegend> beside the chart instead, as the example above does.
Inside a <ChartLegendHoverProvider>, hovering a legend row dims every other series.
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.
className goes on the chart's container, so size and spacing are utility classes.
To pick out one series, give it a strong color and a thicker line, and mute the others with --chart-foreground-muted. strokeWidth sets a line's width (3 px), and its dots grow with it.
A hover lights a whole series, so the tooltip's rows and content receive { series, ranks } rather than one of your rows. formatValue on each <Bump> formats its values in the tooltip.
<BumpChart data={data} rankBy="ascending" showLabels={false}>
<Bump color="var(--chart-1)" dataKey="paylane" label="PayLane" strokeWidth={4} />
<Bump
color="var(--chart-foreground-muted)"
dataKey="cardpay"
label="CardPay"
strokeWidth={2}
/>
<Bump
color="var(--chart-foreground-muted)"
dataKey="quickpay"
label="QuickPay"
strokeWidth={2}
/>
</BumpChart>Where a part renders content of its own, you pass it in. In React:
ChartTooltip:content={({ point, index }) => …}
Loading state
With status="loading" the chart draws skeleton lines that trade places from period to period and ignores the pointer. loadingLabel writes a short line over them, and "ready" draws the real rankings in.
With no data yet, render <BumpChartLoading /> in the chart's place.
Animation
The lines wipe in from left to right over animationDuration (1100 ms), and each dot pops in as the line reaches its period.
Pass animate={false} to draw everything at once.
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.
Series take --chart-1 to --chart-5 in the order you write them, then start over. Past five series, pass color so no two lines share one.
| 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-4 | your theme's | the fourth series |
--chart-5 | your theme's | the fifth series |
--chart-background | --card | dot halos, the gaps between stacked marks |
--chart-grid | --border | grid lines |
--chart-label | --muted-foreground | tick labels |
--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 ("Bump chart" by default). A screen reader can't follow the lines, so put the outcome in ariaDescription, for example who finished first.
- Tab
- Moves focus to the chart, on the top dot of the first period.
- Arrow Right
- Moves to the next dot: down the current period, then on to the next one. ArrowDown does the same.
- Arrow Left
- Moves back one dot. ArrowUp does the same.
- Home
- Jumps to the first dot.
- End
- Jumps to the last dot.
API reference
BumpChart
datareadonly Record<string, unknown>[]
The periods, oldest first: each row holds its label under xDataKey and one value per series under that series' Bump dataKey.
- Type
readonly Record<string, unknown>[]
xDataKey?string
The key of each row's period label.
- Default
"period"
rankBy?"descending" | "ascending" | "none"
How a period's values become ranks: "descending" puts the largest first, "ascending" the smallest (a time, a price); "none" reads the values as ranks already.
- Type
"descending" | "ascending" | "none"- Default
"descending"
showLabels?boolean
Write each series' name at the end of its line.
- Default
true
aspectRatio?string | number
Aspect ratio of the chart, as "width / height" or a number.
- Type
string | number- Default
"2 / 1"
margin?Partial<ChartMargin>
Space around the plot in px. With showLabels, the right side makes room for the names.
- Type
Partial<ChartMargin>
animate?boolean
Animate the lines in on mount, left to right, their dots following.
- Default
true
animationDuration?number
Length of the entrance in milliseconds.
- Default
1100
ariaLabel?string
Accessible name of the chart.
- Default
"Bump chart"
ariaDescription?string
Longer accessible description of the chart.
className?string
Extra class name for the chart container.
style?CSSProperties
Inline styles for the chart container.
children?ReactNode
The chart's parts: one Bump per series, Grid, BarXAxis, BarYAxis and ChartTooltip.
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 chart's entrance.
- Default
"ready"
loadingLabel?string
Centered label shown over the plot while status is "loading".
Bump
dataKeystring
The key of the series' value in each row.
label?string
The series' name at the end of its line and in the tooltip. Defaults to dataKey.
color?string
Colour of the line and its dots. Defaults to the palette's next colour.
strokeWidth?number
Width of the line in px.
- Default
3
formatValue?(value: number) => string
Formats the series' values in the tooltip. Defaults to a grouped number.
- Type
(value: number) => string
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
BarXAxis
tickerHalfWidth?number
Half-width in px of the zone around the date pill inside which tick labels are hidden.
- Default
50
showAllLabels?boolean
Show every category label, even where they overlap, instead of thinning them to maxLabels and to the plot width.
- Default
false
maxLabels?BarLabelCount
Maximum number of category labels when showAllLabels is off. Fewer are shown, evenly spaced, when that many would not fit the plot width. Pass { base, sm, md, lg, xl } to vary it with the chart's width (640, 768, 1024 and 1280 px and up).
- Default
12
BarYAxis
showAllLabels?boolean
Horizontal charts: show every category label instead of thinning to maxLabels.
- Default
true
maxLabels?number
Horizontal charts: maximum number of category labels when showAllLabels is off.
- Default
20
numTicks?number
Vertical charts: target number of value ticks. Grid settings take precedence.
- Default
5
formatLargeNumbers?boolean
Vertical charts: abbreviate values of 1000 and above as thousands, for example 2k.
- Default
true
formatValue?(value: number) => string
Vertical charts: formats a value tick into its label. Overrides formatLargeNumbers.
- Type
(value: number) => string
ChartTooltip
showDatePill?boolean
Show the date pill that rides along the bottom of the plot.
- Default
true
showCrosshair?boolean
Show the vertical crosshair line. Bar charts leave it off unless this is true (the dots and the category pill mark the bar).
- Default
true
showDots?boolean
Show a dot on every series at the hovered position.
- Default
true
dotVariant?"dot" | "ring"
Dot style: a filled "dot" or a transparent "ring" square. Read by BarChart only.
- Type
"dot" | "ring"- Default
"dot"
dotSize?number
Dot radius in px.
- Default
5
dotRadiusFraction?number
Corner radius of the "ring" variant as a fraction of its side (0 is square, 0.5 is a circle). Read by BarChart only.
- Default
0.25
dotScale?number
Multiplier applied to the dot or ring size. Read by BarChart and LiveLineChart.
- Default
1
dotStrokeWidth?number
Stroke width of the dots in px.
- Default
2
indicatorColor?string | ((point: Record<string, unknown>) => string)
Color of the crosshair. Only a string is applied; the function form that bklit-ui accepts is ignored and the default is used.
- Type
string | ((point: Record<string, unknown>) => string)- Default
"var(--chart-crosshair)"
content?(props: { point: Record<string, unknown>; index: number; pinned?: boolean; dismiss?: () => void }) => ReactNode
Replaces the default tooltip panel body. Receives the hovered data row and its index; with pinnable, also whether the panel is pinned and a dismiss that unpins it (for a close button in a pinned panel's detail).
- Type
(props: { point: Record<string, unknown>; index: number; pinned?: boolean; dismiss?: () => void }) => ReactNode
pinnable?boolean
A click (or Enter, or Space) on the chart pins the tooltip where it is: the panel takes the pointer, so its content can grow into detail and hold controls, until another click, Escape or dismiss lets it go.
- Default
false
rows?(point: Record<string, unknown>) => { readonly color: string; readonly label: string; readonly value: string | number }[]
Replaces the default rows (one per series) with your own list of { color, label, value }.
- Type
(point: Record<string, unknown>) => { readonly color: string; readonly label: string; readonly value: string | number }[]
dotColor?string | ((point: Record<string, unknown>, line: ChartLineConfig) => string)
Fill of the tooltip dots. A function receives the hovered row and the series config, and is called again each time the hovered row changes. Defaults to each series' color; a ProfitLossLine's dot takes the color of the hovered value's sign.
- Type
string | ((point: Record<string, unknown>, line: ChartLineConfig) => string)
children?ReactNode
Extra content rendered below the rows in the default panel, for example marker details. Without it, a chart with ChartMarkers lists the markers on the hovered date there.
className?string
Extra class name for the tooltip panel.
springConfig?SpringConfig
Spring for the floating panel when matchCrosshair is on. Defaults to the chart's tooltip spring.
matchCrosshair?boolean
Make the floating panel follow the pointer with the same spring as the crosshair instead of damping.
- Default
false
damping?number
Spring damping for the floating panel when matchCrosshair is off, on bklit's 0 to 100 scale: lower is bouncier, higher slower, 0 moves the panel instantly. The default, 20, is the snappy hover spring (stiffness 3600, damping 120); every other value is bklit's spring for it played six times faster.
- Default
20
indicatorDasharray?string
Dash pattern of the crosshair. Omit for a solid line.
indicatorFadeEdges?IndicatorFadeEdges
Vertical fade of the crosshair: both ends, the top, the bottom, or none (solid).
- Default
"both"
indicatorFadeLength?number
Size of the crosshair's fade, as a percentage of its height (2 to 40).
- Default
10
indicatorEndColor?string
Bottom colour of the crosshair: it ramps from indicatorColor at the top to this at the bottom (composes with the fade).
indicatorEnd?"plot" | "point"
How far down the crosshair reaches: the whole plot, or down to the hovered point of the first series.
- Type
"plot" | "point"- Default
"plot"
dotHaloBlur?number
Blur in px on the dots' halo, for a soft glow.
- Default
0
topOffset?number
Extra gap in px between the top of the plot and the tooltip panel.
- Default
0
dateLabels?readonly string[]
The date pill's text for each data row, in row order (pair it with XAxis labels).
boxSpringConfig?SpringConfig
Spring for the floating panel. Takes priority over matchCrosshair and damping.
indicatorWidth?IndicatorWidth
Thickness of the crosshair: a width in px, or "line" (1px), "thin" (2px), "medium" (4px) or "thick" (8px).
- Default
"line"
BumpChartLoading
margin?Partial<ChartMargin>
Space around the plot in px. Missing sides use the chart's default.
- Type
Partial<ChartMargin>
aspectRatio?string | number
Aspect ratio of the placeholder, as "width / height" or a number.
- Type
string | number- Default
the chart's
label?string
Text shown centered over the skeleton, with a shimmer. Nothing is shown when it is unset or empty.
loadingLabel?string
Deprecated: Use label, the name every chart's placeholder takes..
className?string
Extra class name for the chart container.
Examples
3 examples on React, each live with its code and its own install command.
