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/API | Type | Default | Description |
|---|---|---|---|
data | readonly number[] or readonly T[] | required | Values in input order; missing values leave a gap. |
valueKey | numeric field of T | required with rows | Field holding each value. |
categoryKey | string or number field of T | 1-based position | Field used for tooltip titles (rows only). |
labels | (string | number)[] | - | Tooltip titles indexed like data (number arrays only). |
ariaLabel | string | required | Accessible 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" | detected | Sentiment color override. |
marker | boolean | true | Dot on the latest value. |
tooltip | boolean | false | Hover and keyboard tooltip; makes the sparkline focusable. |
label | string | "Value" | Series name in the tooltip. |
formatValue | (value: number) => string | grouped number | Tooltip values. |
formatCategory | (value: string | number) => string | String | Tooltip titles. |
emptyMessage | ReactNode | null | Shown when fewer than two values exist. |
| Chart host props | see Chart | - | height, initialWidth, ariaDescription, callbacks, className, style. |
createSparklineDefinition(options) | function | - | Same options; returns an extensible TanStack definition. |
SPARKLINE_TREND_COLOR | constant | - | Colors for each trend. |
Accessibility
- Always pass an
ariaLabelthat states the trend; a sparkline is too small to read precisely. - Color follows sentiment; pair it with a
ChartTrendor text that states the change. - Turn on
tooltiponly when individual values matter; it adds a tab stop.