Data & Configuration

Start with Installation if Charts is not yet installed. This guide follows a chart from its first rows through configuration, updates, interaction, exports and cleanup.

For dedicated interactive examples of drawing, navigation, linking, selection, exports and other shared features, see Chart tools.

For calculated overlays, calendar-aware comparisons, forecasts, faceting and performance comparisons, see the separate Analysis guide. These tools preserve source observations and use explicit statistical policies.

Try configuration changes

Switch chart type, update rows, turn value labels or grid lines on and off, and export the result. The example uses only the two registered chart definitions.

Load forecastDownload CSVDownload SVG

Show values Show grid lines

Loading chart…

Create a chart

Give the host an explicit height, then call the factory after the host is mounted. No stylesheet or custom element registration is required.

<div id="revenue-chart" style="width: 100%; height: 360px;"></div>

import { createLineChart } from '@revolist/charts/line';

const container = document.getElementById('revenue-chart')!;
const chart = await createLineChart({
  container,
  data: [
    { month: 'Jan', revenue: 120 },
    { month: 'Feb', revenue: 180 },
    { month: 'Mar', revenue: null },
  ],
  mapping: {
    category: { field: 'month' },
    series: [{ field: 'revenue', label: 'Revenue' }],
  },
  presentation: { title: 'Monthly revenue' },
});

// Later, when your application removes the host:
// chart.destroy();

Each row becomes one category. Values must be finite numbers or explicit null; missing values and numeric strings are rejected. Category keys must be unique by type and value. The converter preserves identities and does not aggregate rows. Use category.label to map a separate string display-label field.

Configure presentation and chart options

Use presentation for titles, legend placement, axis titles and value labels. Use chartOptions for the selected type’s options. Supported options and their ranges are declared by that type’s definition; an unsupported option is rejected.

await chart.update({
  presentation: {
    title: 'Monthly revenue',
    subtitle: 'Actual revenue · € thousands',
    legendPosition: 'bottom',
    yAxisTitle: '€ thousands',
    dataLabels: true,
  },
  chartOptions: { showGridLines: false },
  theme: 'dark',
});

Presentation is replaced as a whole, so include titles you want to retain. To edit an existing chart while keeping other presentation settings:

await chart.update({
  presentation: { ...chart.model.presentation, dataLabels: true },
});

Use explicit datasets and channel bindings

Rows are convenient for simple categorical charts. Use createChartDataset to reuse a conversion, or supply a complete ChartDataset from your own analytical pipeline. Channel bindings reference series IDs, not display labels:

import { createScatterChart } from '@revolist/charts/scatter';

const scatter = await createScatterChart({
  container,
  data: [
    { product: 'A', cost: 20, revenue: 60 },
    { product: 'B', cost: 35, revenue: 90 },
  ],
  mapping: {
    category: { field: 'product' },
    series: [{ field: 'cost' }, { field: 'revenue' }],
  },
  bindings: { x: ['cost'], y: ['revenue'] },
});
scatter.destroy();

Hierarchy charts require hierarchy metadata. Box plots and violins require observations or valid distribution summaries; aggregate totals cannot recover a distribution. Financial charts need explicit OHLC channels. The overview’s live catalog exposes a valid dataset and bindings for every built-in type.

Update, select and export

Updates reuse the last successful field mapping. Await an update before reading a snapshot or exporting. Invalid updates preserve the previous chart.

await chart.update({
  data: [
    { month: 'Apr', revenue: 240 },
    { month: 'May', revenue: 210 },
  ],
});
await chart.update({ interaction: { mode: 'select' } });
// Clicking a point now commits local selection.
await chart.clearSelection();

const csv = chart.getCSV();
await chart.download({ fileFormat: 'svg', fileName: 'monthly-revenue' });
// PNG, CSV and raster PDF downloads are also supported by the native renderer.

Presentation updates replace that settings object. Include titles and other presentation settings you want to keep. undefined preserves a setting owner; {} resets it and arrays replace it.

Choose one type or compose several

Per-type imports such as /line, /grouped-column, /pie and /box-plot expose a definition and a bound factory, for example lineChart and createLineChart. A bound factory keeps its chart type fixed.

For an application that switches types, register only the definitions it needs with createChartFactory from /core. Here is the actual setup used by the live example above. Save it as revenue-chart.ts:

import { createChartFactory } from '@revolist/charts/core';
import { lineChart } from '@revolist/charts/line';
import { groupedColumnChart } from '@revolist/charts/grouped-column';

export const revenueRows = [
  { month: 'Jan', revenue: 120, costs: 80 },
  { month: 'Feb', revenue: 180, costs: 110 },
  { month: 'Mar', revenue: 160, costs: 95 },
  { month: 'Apr', revenue: 240, costs: 140 },
  { month: 'May', revenue: 210, costs: 125 },
  { month: 'Jun', revenue: 290, costs: 165 },
];

// Register only the types this application needs.
const createRevenueChart = createChartFactory([lineChart, groupedColumnChart]);

export function mountRevenueChart(
  container: HTMLElement,
  theme: 'light' | 'dark' = 'light',
  signal?: AbortSignal,
) {
  return createRevenueChart({
    container,
    signal,
    theme,
    chartType: 'line',
    data: revenueRows,
    mapping: {
      category: { field: 'month' },
      series: [
        { field: 'revenue', label: 'Revenue' },
        { field: 'costs', label: 'Costs' },
      ],
    },
    presentation: {
      title: 'Monthly performance',
      subtitle: 'Illustrative data · € thousands',
      legendPosition: 'bottom',
      yAxisTitle: '€ thousands',
    },
    interaction: { mode: 'select' },
  });
}

The returned controller supports both registered types:

import { mountRevenueChart } from './revenue-chart';

const container = document.getElementById('revenue-chart')!;
const chart = await mountRevenueChart(container);
await chart.update({ chartType: 'groupedColumn' });
await chart.update({ chartType: 'line' });
chart.destroy();

The package-root createChart includes the full built-in catalog when arbitrary type switching is needed. Specialized charts retain their data requirements: for example, scatter charts need channel bindings and box plots need source observations or valid distribution summaries. Supply an explicit ChartDataset for analytical data, hierarchy metadata, bindings or distributions. createChartDataset from /core also converts rows separately for reuse.

Customize renderer colors and locale

Every per-type factory also accepts rendererOptions directly. See Chart Customization for all color, label, element-style and advanced SVG controls, including Pivot and geographic usage.

Pass a renderer to a bound factory when your application supplies theme tokens, a palette, or label formatting. This example still loads only the line renderer:

import { createNativeChartsRenderer } from '@revolist/charts/core';
import { createLineChart, lineChart } from '@revolist/charts/line';

const chart = await createLineChart({
  container,
  data: [{ month: 'Jan', revenue: 120 }],
  mapping: { category: { field: 'month' }, series: [{ field: 'revenue' }] },
  renderer: createNativeChartsRenderer([lineChart], {
    palette: ['#6647f0', '#fd7e14'],
    theme: { foreground: '#172033', grid: '#e2e8f0' },
  }),
  localeText: { dataTable: { categoryHeader: 'Month' } },
});
chart.destroy();

Themes, saved state and cleanup

Set theme: 'light' or 'dark' to follow your application’s theme, or pass renderer theme tokens through a custom renderer. theme: 'auto' follows the nearest host data-theme attribute, falling back to the system color preference. Configure labels and titles with presentation, per-type settings with chartOptions, and translations with localeText.

const saved = JSON.stringify(chart.model);
chart.destroy();

const restored = await createLineChart({
  container,
  model: JSON.parse(saved),
});
// Dispose when your component unmounts or route changes.
restored.destroy();

Chart models are version 1 and contain chart state. Pass either rows with a mapping, an explicit dataset, or a saved model. A supplied AbortSignal cancels pending creation and disposes the chart when aborted. Always destroy a chart when its host unmounts; destroy() is idempotent.

Optional integrations and Pivot

• @revolist/charts/echarts accepts an application-supplied ECharts runtime.
• @revolist/charts/vector-pdf accepts a vector PDF encoder runtime.
• @revolist/charts/geographic provides opt-in geographic capability packs with application-supplied providers and assets.

For linked charts built from grouped grid results, queries, drill-down or filter synchronization, use Pivot Charts. Pivot consumes the same chart engine and owns those grid-specific operations.