lab components / Data Visualization

SparkLine

A compact line graph without axes, designed to visually represent numerical series trends within a limited space.

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { SparkLine } from "@siteimprove/fancylab";

#Examples

The SparkLine component features a few properties for adjusting its appearance and functionality. The following sections showcase these properties and explain when to use them.

CodeHTML output

<SparkLine
	series={{
		data: [
			17, 93, 87, 35, 89, 28, 33, 91, 21, 78, 81, 48, 44, 31, 33, 35, 87, 87, 18, 10, 96, 75, 35,
			83, 16, 16,
		],
	}}
/>

#Styling

#Line Color

The lineColor property lets you specify the fill color for the line. If no color is provided, the component will use a default color palette.

CodeHTML output

<SparkLine
	series={{
		data: [43, 9, 92, 6, 35, 83, 16, 16.408],
		lineColor: ColorGreen,
	}}
/>

The lineStyle property allows you to choose one of three available line styles: solid (default), dashed (default), and dotted. For accessible, non-color-dependent components, choose line styles that allow series to be distinguished regardless of their color, especially when working with multiple series.

CodeHTML output

<SparkLine
	series={{
		data: [43, 9, 92, 6, 35, 83, 16, 16],
		lineStyle: "solid",
	}}
/>
<br />
<SparkLine
	series={{
		data: [43, 9, 92, 6, 35, 83, 16, 16],
		lineStyle: "dashed",
	}}
/>
<br />
<SparkLine
	series={{
		data: [43, 9, 92, 6, 35, 83, 16, 16],
		lineStyle: "dotted",
	}}
/>

#Size (TODO: feature to be confirmed)

The size property lets you specify a height for the SparkLine: small, or large (default). Choose a size that's in proportion to the size of the container in which the SparkLine is used.

CodeHTML output

<div style={{ display: "flex" }}>
	<SparkLine
		size="small"
		series={{
			data: [43, 9, 92, 6, 35, 83, 16, 16],
		}}
	/>
	<SparkLine
		size="large"
		series={{
			data: [43, 9, 92, 6, 35, 83, 16, 16],
		}}
	/>
</div>

#Data Formatting

The data-points are displayed through a tooltip when hovering over the SparkLine with the mouse or pointer. The textual formatting of datapoints can be controlled using the following properties:

#Using prefix and/or postfix

Use dataPrefix and/or dataPostfix to format the text by including characters before and after the datapoint value, respectively.

CodeHTML output

<SparkLine
	style={{ width: "300px" }}
	series={{
		data: SERIE_DATA,
		dataPrefix: "+ ",
		dataPostfix: "%",
	}}
/>

#Using a custom formatting function

Use dataFormatter to have more control over the textual formatting of datapoints. In this way, it is also possible to format the numeric value for formats such as currency.

CodeHTML output

<SparkLine
	style={{ width: "300px" }}
	series={{
		data: SERIE_DATA,
		dataFormatter: (value) =>
			toFormattedNumberString({ number: value, locale: "en-US", format: "currency" }),
	}}
/>

#Ranges

By default, the minimum and maximum value occupy the height of the sparkline. Optionally, minY and maxY values can be set.

When the series are all 0

When the series are all 1

When the series goes from 0 to 1

When the series goes from 1 to 0

With custom minY

With custom maxY

CodeHTML output

<div style={{ display: "flex" }}>
	<div style={{ flex: 0.5 }}>When the series are all 0</div>
	<div style={{ border: `1px dashed ${ColorGrayLighter}` }}>
		<SparkLine
			series={{
				data: [0, 0],
			}}
		/>
	</div>
</div>
<br />
<div style={{ display: "flex" }}>
	<div style={{ flex: 0.5 }}>When the series are all 1</div>
	<div style={{ border: `1px dashed ${ColorGrayLighter}` }}>
		<SparkLine
			series={{
				data: [1, 1],
			}}
		/>
	</div>
</div>
<br />
<div style={{ display: "flex" }}>
	<div style={{ flex: 0.5 }}>When the series goes from 0 to 1</div>
	<div style={{ border: `1px dashed ${ColorGrayLighter}` }}>
		<SparkLine
			series={{
				data: [0, 1],
			}}
		/>
	</div>
</div>
<br />
<div style={{ display: "flex" }}>
	<div style={{ flex: 0.5 }}>When the series goes from 1 to 0</div>
	<div style={{ border: `1px dashed ${ColorGrayLighter}` }}>
		<SparkLine
			series={{
				data: [1, 0],
			}}
		/>
	</div>
</div>
<br />
<div style={{ display: "flex" }}>
	<div style={{ flex: 0.5 }}>With custom minY</div>
	<div style={{ border: `1px dashed ${ColorGrayLighter}` }}>
		<SparkLine
			minY={-1}
			series={{
				data: [0, 1],
			}}
		/>
	</div>
</div>
<br />
<div style={{ display: "flex" }}>
	<div style={{ flex: 0.5 }}>With custom maxY</div>
	<div style={{ border: `1px dashed ${ColorGrayLighter}` }}>
		<SparkLine
			maxY={2}
			series={{
				data: [0, 1],
			}}
		/>
	</div>
</div>

#Multiple Series

Display up to 3 series simultaneously on a single SparkLine. Series can have varying sizes.

CodeHTML output

<SparkLine
	style={{ width: "300px", height: "64px" }}
	series={[
		{
			data: [0, 20, 0, 20, 20, 80, 60, 70, 100],
		},
		{
			data: [80, 50, 40, 50, 60, 65, 90, 50, 30],
		},
		{
			data: [10, 80, 40, 35, 10, 35, 10, 20, 50],
		},
	]}
/>

The series can also have different sizes.

CodeHTML output

<SparkLine
	style={{ width: "300px" }}
	series={[
		{
			data: [43, 9, 92, 6, 35, 83, 16, 16],
		},
		{
			data: [16, 83, 92, 35, 6],
		},
		{
			data: [35, 43],
		},
	]}
/>

#Performance

The following example lets you experience how SparkLines perform when rendering a large number of them. It shows a ListTable with 200 rows, where each row has a SparkLine with 3 series and each series has 30 points. Please click the button below to load this list.

CodeHTML output

const translations = {
	"aria-label": `List with ${numberOfItems} SparkLines`,
	noDataFoundLabel: "No data found",
	loadMoreLabel: (count: number) => `Load ${count} more`,
	loadAllLabel: "Load all",
};
const [isListVisible, setListVisibility] = useState<boolean>(false);

const start = Date.now();
useLayoutEffect(() => {
	document.getElementById("render-time")!.innerText =
		"Render time: " + (Date.now() - start) + "ms";
});

return (
	<>
		<div id="render-time"></div>
		<Button onClick={() => setListVisibility(!isListVisible)} variant="primary">
			{isListVisible ? "Hide list" : "Load a large list of SparkLines"}
		</Button>
		{isListVisible && (
			<ListTable
				columns={[
					{
						header: { content: "Description" },
						render: (dto) => dto.description,
						options: { isKeyColumn: true },
					},
					{
						header: { content: "Value" },
						render: (dto) => <SparkLine series={dto.series} />,
					},
				]}
				items={tableData}
				loading={false}
				loadMoreCount={100}
				style={{ marginTop: "10px" }}
				{...translations}
			/>
		)}
	</>
);

#Properties

CodePropsHTML output

Property	Description	Defined
seriesRequired	`\| object \| object[]`Data series	YesNo
sizeOptional	`"large" \| "small"`Size of the spark line (defaults to `"large"`)	YesNo
minYOptional	`number`Optional min Y value	YesNo
maxYOptional	`number`Optional max Y value	YesNo
pointSizeOptional	`number`Radius used on svg strike points	YesNo
aria-labelOptional	`string`Label of the spark line	YesNo
aria-labelledbyOptional	`string`ID of an an element that labels this spark line	YesNo
aria-describedbyOptional	`string`ID of an an element that describes the spark line content	YesNo
data-observe-keyOptional	`string`Unique string, used by external script e.g. for event tracking	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo

You need to quickly convey trends or patterns within numerical data.
Space is limited and a full-fledged chart isn't feasible.
You want to embed visual data representations within tables or lists.

#Placement

SparkLine is typically used in the following places:

Table cells: To illustrate trends within tabular data.
List items: To quickly visualize the progress or status associated with each item.
Dashboard widgets: To provide compact summaries of key metrics.

#Style

Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your SparkLine to existing components for visual consistency.

#Do not use when

Precise numerical values are critical for the user.
The data set is too small (fewer than 3-4 points) or too complex for a clear representation.
Comparing multiple data sets with widely different scales.
Users need to interact with specific data points through annotations or tooltips.

#Accessibility

#For designers

Ensure line styles provide differentiation beyond color.

#For developers

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

For data description,

Use verbs like "increase," "decrease," "fluctuate," "stabilize," or "peak."
Quantify when appropriate: Include specific numbers or percentages to add precision.
Avoid vague terms: Don't rely on words like "good," "bad," or "better" without providing context or specific data points.

SparkLine

This is a Lab component!

#Examples

#Styling

#Line Color

#Line Style

#Size (TODO: feature to be confirmed)

#Data Formatting

#Using prefix and/or postfix

#Using a custom formatting function

#Ranges

#Multiple Series

#Performance

#Properties

#Guidelines

#Best practices

#General

#Placement

#Style

#Do not use when

#Accessibility

#For designers

#For developers

#Writing