Sparkline

Axis-free inline trend mark for KPI cards and dense tables.

stable

Quick Preview

Revenue₦4.2M
New listings128
Cancellations12

Usage

import { Sparkline } from "@giddaa-housing/ui/sparkline";

<Sparkline data={[40, 44, 42, 55, 58]} ariaLabel="Revenue, trending up" />
<Sparkline data={[40, 44, 42, 55, 58]} variant="area" ariaLabel="Revenue, trending up" />
<Sparkline data={[40, 44, 42, 55, 58]} variant="bar" ariaLabel="Revenue, trending up" />

Pass a number[] (nulls leave a gap) or rows with valueKey. variant picks the mark: "line", "area", or "bar". Color follows the direction of the data, first value to last: success up, danger down, secondary flat; override it with trend. Width is parent-driven and size sets the height (24, 32, or 44px). Fewer than two values render emptyMessage, blank by default.

Examples

KPI tiles

Revenue₦4.2M
New listings128
Cancellations12

Tooltip

tooltip makes the sparkline focusable and shows each point. Tooltip titles come from categoryKey with rows, or labels with a plain array; formatValue formats the value.

Revenue · trailing 7 months
<Sparkline
  data={revenue}
  valueKey="value"
  categoryKey="month"
  variant="area"
  tooltip
  label="Revenue"
  formatValue={(value) => `₦${value.toLocaleString("en-NG")}`}
  ariaLabel="Revenue, January to July, trending up"
/>

Props

Prop/APITypeDefaultDescription
datareadonly number[] or readonly T[]requiredValues in input order; missing values leave a gap.
valueKeynumeric field of Trequired with rowsField holding each value.
categoryKeystring or number field of T1-based positionField used for tooltip titles (rows only).
labels(string | number)[]-Tooltip titles indexed like data (number arrays only).
ariaLabelstringrequiredAccessible name; state the direction, e.g. "trending up".
variant"line" | "area" | "bar""line"Stroke, stroke over a wash, or one thin bar per point.
size"sm" | "md" | "lg"inherited, otherwise "md"Height and stroke/dot scale (SPARKLINE_LAYOUT).
trend"up" | "down" | "flat"detectedSentiment color override.
markerbooleantrueDot on the latest value.
tooltipbooleanfalseHover and keyboard tooltip; makes the sparkline focusable.
labelstring"Value"Series name in the tooltip.
formatValue(value: number) => stringgrouped numberTooltip values.
formatCategory(value: string | number) => stringStringTooltip titles.
emptyMessageReactNodenullShown when fewer than two values exist.
Chart host propssee Chart-height, initialWidth, ariaDescription, callbacks, className, style.
createSparklineDefinition(options)function-Same options; returns an extensible TanStack definition.
SPARKLINE_TREND_COLORconstant-Colors for each trend.

Accessibility

  • Always pass an ariaLabel that states the trend; a sparkline is too small to read precisely.
  • Color follows sentiment; pair it with a ChartTrend or text that states the change.
  • Turn on tooltip only when individual values matter; it adds a tab stop.

On this page