A word-sized trend in plain SVG and CSS, no charting library: a line, an area or a row of bars from a list of numbers, with its last point marked. It draws itself on arrival, tweens into new data (a week into a month and back), colours itself by its news if you ask, and lets people scrub it with the pointer or the arrow keys while its value rolls in a small readout. Its trend and change are readable by screen readers and agents.
See it as an AI agent does.See this component the way an AI agent does.
Installation
npx shadcn@latest add @keyframery/sparklineThis adds components/keyframery/sparkline.tsx and its primitive to your project, and installs UI SDK. The motion tokens are added to your global CSS the first time you install a component.
Usage
import { Sparkline } from "@/components/keyframery/sparkline"
export default function Usage() {
return <Sparkline data={[12, 14, 13, 18, 21, 19, 24]} label="Revenue" period="last 7 days" />
}Examples
Coloured by its news
trendColor draws a rising line green and a falling one red. Refunds should fall, so downIsGood turns the colour round.
Bars, a target and the high and low
type="bar" grows the bars one after another. reference draws a dashed line at a value; extremes marks the highest and lowest point.
Read the point under the pointer
onActiveIndexChange tells you which point someone is reading, by pointer or arrow keys, so a headline can follow it.
Motion
| Move | What you see |
|---|---|
| Draw | A line draws itself from the left with its area unrolling under it; the last point pops in once the line reaches it. |
| Cascade | Bars grow from the baseline one after another, left to right, in about half a second whatever their number. |
| Spring | New data tweens the line, the area, every bar, the reference line and the last point to their new places. Up to 97 points, any length tweens into any other. |
| Glide | While someone scrubs, a hairline and a dot ride to the point under the pointer and the readout follows them, swinging inward near the edges. |
| Roll | The readout's value rolls to each new number. |
Timing and springiness follow the motion style you set. To change how fast this sparkline moves, pass speed:
<Sparkline speed="fast">
…
</Sparkline>"fast" is 0.6×, "slow" 1.4×, and a number sets the multiplier. With reduced motion turned on, nothing moves: changes happen at once or with a short fade.
Theming
Set these CSS variables on the component or a parent. Leave them unset to follow the light and dark theme. The open Customize panel below the preview lets you try these settings.
| Variable | What it changes | Default |
|---|---|---|
--sparkline-color | The marks, without trendColor | --chart-1 |
--sparkline-positive | Good news, with trendColor | oklch(0.62 0.16 150) |
--sparkline-negative | Bad news, with trendColor | --destructive |
--sparkline-height | The height | 2.5rem |
--sparkline-stroke | The line's width | 1.75px |
--sparkline-dot | The dots' size | 6px |
--sparkline-surface | The ring round the dots (the surface it sits on) | --background; --card in dark |
--sparkline-reference | The dashed reference line | --muted-foreground |
API reference
Every part takes className and children, along with the props of the element it renders. The parts are rendered by UI SDK, so they also take render, to draw your own element, and a function of their state for className and style.
Sparkline
Renders a <div>, and takes its props too.
Prop
Type
Roll
Prop
Type
SparklineBars
Renders a <div>, and takes its props too.
Prop
Type
Other parts
These take the props of the element they render, and nothing else:
SparklinePlot: a<div>SparklineAreaSparklineBar: a<div>SparklineCursor: a<div>SparklineEnd: a<div>SparklineExtreme: a<div>SparklineLineSparklineMarker: a<div>SparklinePoint: a<div>SparklinePoints: a<div>SparklineReadout: a<div>SparklineReference: a<div>SparklineSvg
Keyboard
| Key | What it does |
|---|---|
| Tab | Moves focus to the sparkline's points as one tab stop and shows the point's value. |
| ArrowRight | Moves to the next point and shows its value. |
| ArrowLeft | Moves to the previous point. |
| Home | Moves to the first point. |
| End | Moves to the last point. |
| Escape | Hides the readout; any arrow brings it back. |
Accessibility
Roles, keyboard and focus are declared on the component's UI SDK primitive, and state is announced through the matching ARIA attributes. More in Accessibility.
Built on UI SDK's core
UI SDK doesn't ship a sparkline, so this one is defined with its core: one definePrimitive in components/keyframery/core/sparkline-core.ts, with no React in it. UI SDK's adapters can render that same definition in Vue, Svelte, Solid and web components. To keep your own styling and take only the motion, import from @/components/keyframery/primitives/sparkline.
Questions
How does the animated Sparkline for UI SDK move?
Draw: A line draws itself from the left with its area unrolling under it; the last point pops in once the line reaches it. Cascade: Bars grow from the baseline one after another, left to right, in about half a second whatever their number. Spring: New data tweens the line, the area, every bar, the reference line and the last point to their new places. Up to 97 points, any length tweens into any other. Glide: While someone scrubs, a hairline and a dot ride to the point under the pointer and the readout follows them, swinging inward near the edges. Roll: The readout's value rolls to each new number.
Do I need Motion or Framer Motion for the animated Sparkline?
No. Every move is plain CSS, so there is nothing to install besides the component and UI SDK.
UI SDK has no sparkline. How is this one built on UI SDK?
Its behaviour is one definition written with UI SDK's core (definePrimitive), in components/keyframery/core/sparkline-core.ts. Its parts are rendered by UI SDK's adapter, so they take render, state-based class names and data-slot, like every UI SDK component.
What happens to the Sparkline when someone turns on reduced motion?
Nothing moves. State changes happen at once, or with a short fade.
More in Data
All componentsData table
The full list screen on top of Table, with no table library: give it data and columns and it owns the search, faceted filters with live counts, the sort, hidden columns, row selection, the page and the page size, each one controlled or not so a page can keep it in the URL. Rows cascade in after a sort or a page turn, a hidden column folds away while the others close the gap, Reset slides in while anything is filtered, and a bulk bar rises from the bottom centre while rows are selected.
Stat
The KPI card of an admin dashboard: a label, one big number, the change as a coloured pill with an arrow, a comparison line, an optional icon and room for a sparkline, with a loading state at the parts' own size. When the numbers change the value rolls digit by digit, the delta's arrow turns to its new direction and the sparkline tweens. StatGroup sets several on one surface with hairlines between them, four across, then two, then one, by container queries.