Charts

Sparkline

A tiny inline chart (line or bar) for embedding in cards, tables, and tight spaces.

import { Sparkline } from "metricui";

Use Sparkline when you need inline micro-charts inside cards, tables, or other tight spaces. It provides a compact trend visualization without axes or labels — ideal for showing direction and shape at a glance. For full-sized time-series charts with axes and legends, use LineChart or AreaChart instead.

Basic Example

Pass an array of numbers to render a line sparkline. The component fills its container width and defaults to 40px tall.

<Sparkline
  data={[10, 15, 12, 18, 14, 22, 19]}
  trend="positive"
/>

Bar Type

Set type="bar" for a bar sparkline. Useful for discrete values like daily counts.

<Sparkline
  data={[4, 7, 3, 8, 5, 9, 6, 11, 8]}
  type="bar"
  color="#6366F1"
  height={40}
/>

Reference Lines & Bands

Add a referenceLine to mark a target or average, and a band to shade a normal range. Both work with line and bar types.

<Sparkline
  data={[65, 72, 68, 80, 75, 82, 78, 90, 85]}
  trend="positive"
  height={48}
  referenceLine={{
    value: 75,
    label: "Avg",
    style: "dashed",
  }}
  band={{
    from: 70,
    to: 85,
    color: "#10B981",
    opacity: 0.08,
  }}
  interactive
  showEndpoints
/>

Trend Coloring

Enable trendColoring to automatically color the line based on trend direction — green for positive, red for negative. Pass "invert" to flip the colors (useful when lower is better, like error rates).

<Sparkline
  data={[20, 25, 28, 32, 38, 42]}
  trendColoring
  trend="positive"
  showEndpoints
/>

<Sparkline
  data={[45, 42, 38, 41, 35, 32]}
  trendColoring
  trend="negative"
  showEndpoints
/>

Interactive Tooltips

Set interactive to enable hover tooltips. Use the format prop to control how values are displayed in the tooltip.

<Sparkline
  data={[1200, 1350, 1100, 1580, 1420, 1690, 1530]}
  trend="positive"
  interactive
  format="currency"
  height={48}
  showMinMax
/>

Props

Prop	Type	Default	Description
`data`*	`(number \| null)[]`	—	Data points. null values create gaps in the line.
`trend`	`"positive" \| "negative" \| "neutral"`	`"neutral"`	Trend direction for auto-coloring.
`color`	`string`	—	Override color (CSS color string). Defaults to theme-aware trend color.
`type`	`SparklineType`	`"line"`	"line" or "bar".
`height`	`number`	`40`	Height in px. Set to undefined to fill container.
`width`	`number`	—	Width in px. Default: fills container.
`curve`	`"monotoneX" \| "linear" \| "step" \| "natural"`	`"monotoneX"`	Curve interpolation for line type.
`fill`	`boolean`	`true`	Show gradient area fill under the line.
`animate`	`boolean`	`true`	Entrance animation. Falls back to config.animate.
`showEndpoints`	`boolean`	`false`	Show dots on first and last data points.
`showMinMax`	`boolean`	`false`	Show dots + subtle labels on min/max values.
`trendColoring`	`boolean \| "invert"`	`false`	Auto-color based on trend direction. Pass "invert" to flip (green = down, red = up).
`referenceLine`	`SparklineReferenceLine`	—	Horizontal reference line (e.g., average or target).
`band`	`SparklineBand`	—	Shaded band region (e.g., normal range).
`interactive`	`boolean`	`false`	Enable interactive tooltip on hover.
`format`	`FormatOption`	—	Format option for tooltip values.
`formatTooltip`	`(value: number) => string`	—	Legacy: direct tooltip formatter function. Takes precedence over `format`.
`strokeWidth`	`number`	`1.5`	Line stroke width in px.
`className`	`string`	—	Additional CSS class for the root container.
`classNames`	`{ root?: string; svg?: string; tooltip?: string }`	—	Sub-element class name overrides.
`id`	`string`	—	HTML id attribute.
`data-testid`	`string`	—	Test id.

Notes

Uses forwardRef.
Uses forwardRef — attach a ref to the root div.
When placed inside a sized container, omit height/width to fill it automatically.
The line sparkline uses clip-path animation for a draw-on entrance effect.
Bar sparkline uses scaleY animation per bar with staggered delays.
formatTooltip (legacy function) takes precedence over the format prop.
Null values in the data array create visible gaps between line segments.