Sparkline

ChartsSince 0.3.0

import { Sparkline } from '@absoluteui/components/sparkline';
import '@absoluteui/components/sparkline/style.css';

Using Angular? See Sparkline for Angular.

What it does

A word-sized trend graphic (line or bars) for text, table cells, and KPI tiles. It is a static image (role="img") whose generated accessible name summarizes the data: label, value count, first and last value, minimum, and maximum. It is not focusable and has no tooltip; creating one needs no layout reads, so hundreds per page are cheap. It does not use the chart frame, so importing it does not pull in Line, Bar, or Pie chart code.

When to use

• Showing the shape of a trend next to a number (KPI tiles, table cells, sentences).
• Many small trends on one page (cheap to create, no layout reads).

When not to use

• When users need to read individual values: use Line Chart or Bar Chart (tooltips, keyboard, data table).
• As the only source of important information.

Examples

Inline line sparkline next to a KPI

import { Sparkline } from '@absoluteui/components/sparkline';

const host = document.createElement('span');
document.body.append(host);
Sparkline.create(host, { label: 'Weekly sign-ups, last 12 weeks', values: [120, 132, 128, 150, 149, 170, 181, 176, 195, 210, 205, 230] });

Bar sparkline with negatives and a fixed domain

import { Sparkline } from '@absoluteui/components/sparkline';

const host = document.querySelector<HTMLElement>('#net');
if (host) {
  const spark = Sparkline.create(host, { label: 'Net change per day', values: [4, -2, 6, null, -5, 8], variant: 'bar', color: 3, min: -10, max: 10 });
  spark.update({ values: [4, -2, 6, 3, -5, 8] });
}

Usage

import { Sparkline } from '@absoluteui/components/sparkline';
import '@absoluteui/components/sparkline/style.css';

for (const cell of document.querySelectorAll<HTMLElement>('[data-trend]')) {
  const values = (cell.dataset.trend ?? '').split(',').map(Number);
  Sparkline.create(cell, { label: cell.dataset.label ?? 'Trend', values, variant: 'bar' });
}

More usage

import { Sparkline } from '@absoluteui/components/sparkline';

const host = document.createElement('span');
document.body.append(host);
Sparkline.create(host, { label: 'Weekly sign-ups', values: [120, 132, 150, 170] });

Anatomy

<span class="aui-sparkline aui-sparkline--line aui-sparkline--c1">
  <svg class="aui-sparkline__svg" role="img" aria-label="Weekly sign-ups: 12 values, from 120 to 230, minimum 120, maximum 230." viewBox="0 0 100 24" preserveAspectRatio="none">
    <path class="aui-sparkline__line"/>  <path class="aui-sparkline__last"/>          (line)
    <rect class="aui-sparkline__bar [aui-sparkline__bar--last]"/> <path class="aui-sparkline__baseline"/>   (bar)
  </svg>
</span>

API reference

Factory

Sparkline.create(host: HTMLElement, options: SparklineOptions): Sparkline

Global configuration key: sparkline (see Configuration).

Options

Option	Type	Default	Description
label	string		What the values are, for example “Revenue, last 12 months”; starts the accessible name. Required.
values	readonly (number | null)[]		Values in order; null, NaN, and infinities are gaps. Required.
variant	'line' | 'bar'	"line"	Line or bars (bars include zero and draw negatives below a baseline).
color	1 | 2 | 3 | 4 | 5 | 6 | 7 | 8	1	Palette slot (color-chart-<n>).
min	number		Fixed domain minimum (for comparable sparklines).
max	number		Fixed domain maximum.
valueFormat	Intl.NumberFormatOptions		Number format for the accessible name.
formatValue	(value: number) => string		Custom value text for the accessible name.
valueText	string		Replaces the generated accessible name.
highlightLast	boolean	true	Mark the last value (dot for line, full opacity for bar). Globally configurable.
locale	string	"en-US"	Number, date, and message locale. Globally configurable. Inherited from common configuration.
direction	'ltr' | 'rtl'	"ltr"	rtl mirrors the category/x axis, the value axis side, and Left/Right arrow keys. Globally configurable. Inherited from common configuration.

Properties

Property	Type	Description
host	HTMLElement	The host element.
element	SVGSVGElement	The svg role=“img”.
summary	string	The accessible name (generated or valueText).

Methods

Method	Description
update(options: Partial<SparklineOptions>): void	Merge, validate, and re-render.
destroy(): void	Remove rendering, classes, and the configuration subscription.

CSS classes

All rules live in the aui.components cascade layer, so application styles override them without specificity battles.

Class	Purpose
aui-sparkline	Host; inline-block, 6em x 1.5em by default (set inline-size / block-size to resize).
aui-sparkline--line / --bar	Variant modifiers.
aui-sparkline--c1 ... --c8	Palette slot; sets –aui-sparkline-color.
aui-sparkline__svg / __line / __dot / __last / __bar / __bar--last / __baseline	SVG and its parts (non-scaling strokes).

Design tokens

Tokens this stylesheet reads (verified in CI). Override them in a theme or with the Theme Designer.

--aui-color-chart-1 | --aui-color-chart-2 | --aui-color-chart-3 | --aui-color-chart-4 | --aui-color-chart-5 | --aui-color-chart-6 | --aui-color-chart-7 | --aui-color-chart-8 | --aui-color-chart-axis

TypeScript definitions

interface SparklineConfig { highlightLast: boolean }
interface SparklineOptions extends Partial<SparklineConfig> {
  label: string;
  values: readonly (number | null)[];
  variant?: 'line' | 'bar';
  color?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
  min?: number;
  max?: number;
  valueFormat?: Intl.NumberFormatOptions;
  formatValue?: (value: number) => string;
  valueText?: string;
  locale?: string;
  direction?: 'ltr' | 'rtl';
}

Accessibility

Pattern: Static informative image: svg role=“img” with a generated accessible name (WAI Images tutorial, informative images).

Keyboard

Key	Context	Action
None	Any	Not focusable; the accessible name carries the summary. Use Line Chart for keyboard exploration.

Roles

Element	Role
svg.aui-sparkline__svg	img

ARIA attributes

Attribute	Element	Value
aria-label	svg	Localized “{label}: {count} values, from {first} to {last}, minimum {min}, maximum {max}.” (or valueText)

Focus

Not focusable.

WCAG 2.2 success criteria addressed

Criterion	Level	Note
1.1.1 Non-text Content	A
1.4.1 Use of Color	A
1.4.11 Non-text Contrast	AA
4.1.2 Name, Role, Value	A

Automated test results: Accessibility and compliance.

Notes and known caveats

• Meaning is carried by the accessible name and the surrounding text, not by color.
• Forced colors draw the sparkline in CanvasText.
• No animation.
• Individual values are not exposed; keep the key value in visible text next to the sparkline.
• Manual screen-reader verification is pending.

Behavior

States

line, bar, empty (“{label}: no data.”), single value (“{label}: {value}.”).

State transitions

From	Trigger	To
any	update({ values })	re-rendered, new accessible name
line	update({ variant: 'bar' })	bars

Accessibility notes

• Keep the key value in visible text next to the sparkline; individual values are not exposed.
• Meaning is carried by the accessible name and surrounding text, not by color.
• Forced colors draw it in CanvasText. No animation.
• Manual screen-reader verification is pending.

Responsive behavior

Scales with its box through the viewBox (preserveAspectRatio="none", non-scaling strokes). The default size is in em, so it follows the text size.

Right-to-left

direction: 'rtl' puts the first value at the right.

Theming

Stroke and bars use color-chart-<color> (3:1 against surfaces in all themes); the zero baseline uses color-chart-axis.

Global configuration

configureAbsoluteUI({ components: { sparkline: { highlightLast: false } } });

Component configuration

Instance options override global and theme defaults. All options are dynamic.

Security

The accessible name is an attribute value; SVG is built with createElementNS. No innerHTML or style attributes.

Data handling

No persistence, network access, or telemetry.

Performance

Budget: under 1 ms per instance (30 values; e2e performance test, average of 200). No layout reads and no resize observer.

Supported data scale

One to a few hundred values each; bars create one rect per value.

Edge cases

• Gaps split the line; isolated values are drawn as dots.
• All values equal: a flat line mid-height.
• Bars always include zero; negative bars hang below a baseline.
• Values outside a fixed min/max are clamped.

Errors

Code	Category	Cause
SPARKLINE_OPTIONS	configuration	Missing label, non-numeric values, invalid variant or color, max <= min, invalid formatters.
CFG_INVALID_VALUE / CFG_UNKNOWN_OPTION	configuration	Invalid or unknown configuration.

A failed construction leaves the host untouched.

Known limitations

• Not interactive; minimum and maximum are not marked visually.
• Manual screen-reader verification is pending.

Unsupported scenarios

• Axes, labels, legends, tooltips.
• Win/loss and bullet variants.