Chart Library

A framework-agnostic, composable charting library built on D3.js with TypeScript.

Features

• Framework Agnostic - Works with vanilla JS, React, Vue, Svelte, or any framework
• Composable Architecture - Build charts by composing components
• Multiple Chart Types - XYChart (lines, areas, bars), WordCloudChart, DonutChart, PieChart, and GaugeChart
• Radial Value Labels - Pie and donut charts support optional on-chart labels with custom formatters
• Optional Gauge Animation - Animate gauge value transitions with gauge.animate
• Stacking Control - Bar stacking modes with optional reversed visual series order
• Flexible Scales - Band, linear, time, and logarithmic scales
• Explicit or Responsive Sizing - Set top-level width/height or let the container drive size
• Auto Resize - Built-in ResizeObserver handles responsive behavior
• Responsive Policy - Chart-level container-query overrides for theme and components
• Type Safe - Written in TypeScript with full type definitions
• Data Validation - Built-in validation with helpful error messages
• Auto Colors - Smart color palette with sensible defaults

Installation

npm install @internetstiftelsen/charts

Local Development

pnpm dev

Runs the interactive demo app (index.html) with sidebar controls and Chart/Data/Showcase tabs.

pnpm dev:docs

Runs the marketing landing page (docs.html) built on @internetstiftelsen/styleguide.

Build Targets

pnpm build

Builds the publishable chart library output into dist.

pnpm build:docs

Builds the static marketing site into dist-docs (used for Pages deploys).

pnpm build:demo

Builds the demo app using the default Vite config.

Quick Start

import { XYChart } from '@internetstiftelsen/charts/xy-chart';
import { Line } from '@internetstiftelsen/charts/line';
import { XAxis } from '@internetstiftelsen/charts/x-axis';
import { YAxis } from '@internetstiftelsen/charts/y-axis';

const data = [
    { date: '2023', revenue: 100, expenses: 80 },
    { date: '2024', revenue: 150, expenses: 90 },
];

const chart = new XYChart({ data });

chart
    .addChild(new XAxis({ dataKey: 'date' }))
    .addChild(new YAxis())
    .addChild(new Line({ dataKey: 'revenue' }))
    .addChild(new Line({ dataKey: 'expenses' }));

chart.render('#chart-container');

Use top-level width and height for fixed-size charts, or omit them to size from the render container.

Theme overrides are deep-partial, so nested overrides like theme.axis.fontSize preserve the rest of the theme defaults.

Responsive overrides are declarative and merge all matching breakpoints in declaration order:

const chart = new XYChart({
    data,
    responsive: {
        breakpoints: {
            sm: {
                maxWidth: 640,
                theme: {
                    axis: {
                        fontSize: 11,
                    },
                },
                components: [
                    {
                        match: { type: 'xAxis' },
                        override: { display: false },
                    },
                ],
            },
            md: {
                minWidth: 641,
                maxWidth: 768,
                theme: {
                    axis: {
                        fontSize: 12,
                    },
                },
            },
        },
    },
});

Word Cloud

import { WordCloudChart } from '@internetstiftelsen/charts/word-cloud-chart';

const data = [
    { word: 'internet', count: 96 },
    { word: 'social', count: 82 },
    { word: 'news', count: 75 },
];

const chart = new WordCloudChart({
    data,
    wordCloud: {
        minValue: 5,
        minWordLength: 3,
        minFontSize: 3,
        maxFontSize: 20,
        padding: 1,
        spiral: 'archimedean',
    },
});

chart.render('#word-cloud');

minFontSize and maxFontSize are percentages of the smaller plot-area dimension and define the relative size range passed into d3-cloud. The chart expects flat { word, count } rows, aggregates duplicate words after trimming, and maps theme typography and colors directly into the layout and rendered SVG.

Export

chart.export() supports svg, json, csv, xlsx, png, jpg, and pdf.

await chart.export('png', { download: true });
await chart.export('csv', { download: true, delimiter: ';' });
await chart.export('xlsx', { download: true, sheetName: 'Data' });
await chart.export('pdf', { download: true, pdfMargin: 16 });

xlsx and pdf are lazy-loaded and require optional dependencies (xlsx and jspdf) only when those formats are used.

Import

toChartData() converts tab-delimited string input into chart JSON data. It auto-detects grouped and normal (flat) table layouts.

import { toChartData } from '@internetstiftelsen/charts/utils';
import { XYChart } from '@internetstiftelsen/charts/xy-chart';

const data = toChartData('\t\tDaily\tWeekly\nAll users\tSegment A\t85%\t92%\n\tSegment B\t84%\t91%', {
    categoryKey: 'Category',
});

const chart = new XYChart({ data });
chart.render('#chart-container');

The parser supports JSON-escaped string payloads and grouped carry-forward row structure (blank first column on continuation rows).

Supported input shapes:

• Plain tab-delimited strings
• JSON-escaped string payloads

Auto-detection behavior:

• Grouped rows when a carry-forward group structure is present
• Flat rows when no grouped continuation rows are detected

Grouped parsing rules:

• Header row starts with two structural columns (group, category) before metrics
• Continuation rows leave the first column blank to inherit the previous group
• Blank separator rows are ignored

Documentation

• Getting Started - Installation, Vanilla JS, React integration
• XYChart - Line, area, and bar charts API
• WordCloudChart - Word frequency visualization API
• DonutChart - Donut/pie charts API
• PieChart - Pie chart API
• GaugeChart - Gauge chart API
• Components - Axes, Grid, Tooltip, Legend, Title
• Theming - Colors, fonts, and styling

Browser Support

Modern browsers with ES6+ support. Uses D3.js v7.

License

MIT