Async data & retry

Load viewport-aware data with native loading and retry feedback. This feature belongs to @revolist/charts and can be used without Pivot or a grid.

Try it live

Choose Reload data to simulate a refreshed source. Choose Simulate failed request to show native error/retry feedback, then use Retry to recover. The last accepted plot remains visible during loading and failure.

This example uses an in-memory asynchronous provider with a short delay. No backend or network service is required. Navigation supplies the requested viewport and pixel width.

Reload data Simulate failed request

Loading chart…

Inspect live chart state

The chart uses the native Charts renderer. Buttons outside the plot are example application controls calling the public API.

Complete chart setup with sample data

Install Charts using the installation guide, then run this setup after the host mounts. The data is illustrative. Additional actions for this tool are explained below.

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

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

const rows = [
  {
    "date": 1767225600000,
    "month": "Jan",
    "revenue": 65,
    "costs": 45
  },
  {
    "date": 1769904000000,
    "month": "Feb",
    "revenue": 82,
    "costs": 50
  },
  {
    "date": 1772323200000,
    "month": "Mar",
    "revenue": 76,
    "costs": 48
  },
  {
    "date": 1775001600000,
    "month": "Apr",
    "revenue": 95,
    "costs": 65
  },
  {
    "date": 1777593600000,
    "month": "May",
    "revenue": 110,
    "costs": 72
  },
  {
    "date": 1780272000000,
    "month": "Jun",
    "revenue": 102,
    "costs": 68
  },
  {
    "date": 1782864000000,
    "month": "Jul",
    "revenue": 121,
    "costs": 80
  },
  {
    "date": 1785542400000,
    "month": "Aug",
    "revenue": 115,
    "costs": 76
  },
  {
    "date": 1788220800000,
    "month": "Sep",
    "revenue": 135,
    "costs": 89
  },
  {
    "date": 1790812800000,
    "month": "Oct",
    "revenue": 128,
    "costs": 85
  },
  {
    "date": 1793491200000,
    "month": "Nov",
    "revenue": 145,
    "costs": 92
  },
  {
    "date": 1796083200000,
    "month": "Dec",
    "revenue": 155,
    "costs": 100
  }
];
const mapping = {
  "category": {
    "field": "date",
    "label": "month"
  },
  "series": [
    {
      "field": "revenue",
      "label": "Revenue"
    },
    {
      "field": "costs",
      "label": "Costs"
    }
  ]
};
const createChart = createChartFactory([lineChart, groupedColumnChart, columnLineChart]);
const container = document.getElementById('chart')!;
const chart = await createChart({
  container,
  data: rows,
  mapping,
  "chartType": "line",
  "axes": {
    "x": {
      "scale": "time"
    }
  },
  "presentation": {
    "title": "Monthly performance",
    "subtitle": "Illustrative data · 2026",
    "legendPosition": "bottom"
  },
  "interaction": {
    "mode": "select",
    "selectionMode": "multiple"
  },
  "navigation": {
    "enabled": true,
    "navigator": true
  }
});

// When the host unmounts:
// chart.destroy();

API and configuration

import { createChartDataset, type ChartDataSource } from '@revolist/charts/core';
// rows and mapping can come from the complete sample setup above.
const dataSource: ChartDataSource = {
  revision: 1,
  async load(request, { signal }) {
    if (signal.aborted) throw new DOMException('Aborted', 'AbortError');
    // Replace this conversion with an abortable fetch in your application.
    return {
      dataset: createChartDataset(rows, mapping),
      fullDomain: { x: { scale: 'time', min: rows[0].date, max: rows.at(-1)!.date } },
      revision: 1,
    };
  },
};
await chart.setDataSource(dataSource);
await chart.reloadData();

Support and behavior

A response includes a valid dataset, stable whole-source fullDomain and a revision matching the attached source. Detail and overview requests are separate. Superseded requests are aborted and stale responses cannot overwrite newer accepted data. Source mode rejects row transactions and direct data replacement. Functions, source handles, loading state and overview stay outside saved models; reattach a source after restoration.

State and cleanup

Authored settings are available through chart.model. Updates replace whole settings objects: spread fields you want to retain, and await the returned promise before reading state or exporting. Destroy the controller when its host unmounts.

All chart tools · Chart types · Data & Configuration

Named X domain metadata

Source requests retain independent viewport.xAxes windows. Return matching continuous bounds in fullDomain.xAxes[id] for each requested named axis; missing or mismatched bounds reject without committing the response. fullDomain.y describes the primary value axis; fullDomain.yAxes[id] supplies secondary/named numeric Y bounds. Requested named Y windows require matching full-domain metadata. Without provider bounds, authored/local bounds govern supported local navigation. Runtime async source acquisition requires a numeric or time X domain; categorical bar/column acquisition is not added by their value-axis support. See named-axis contracts.

Histogram sources

Histograms require a complete global summary in dataset.analyticalFrame.derived.histogram for each detail response. The raw matrix may contain only loaded rows. Histogram requests include bin-count, aggregation and numeric-X hints; the shared runtime derives the navigator from complete statistics without a second overview request. See every histogram summary/request field, source invariant and CSV limitation. createStandalonePivotChart also accepts dataSource; its returned ref exposes setDataSource and reloadData through the shared runtime.

Windowed providers can supply fullDomain.yAxes for secondary/named numeric Y bounds and receive the corresponding viewport.yAxes. Requested named windows require matching domains; see value navigation.

Provider request and ownership reference

Field	Contract
Source revision	Nonempty string or finite number identifying the attached source generation; distinct from numeric dataset.revision. Responses must match it.
Request purpose	'detail' for committed data, 'overview' for a separate full-domain navigator. Overview data is transient and does not replace exports’ detail dataset.
Request viewport	Captured primary/named X and Y windows in public coordinates. Epoch instants remain the time identity.
Request bindings	Captured public semantic channel bindings.
Request pixelWidth	Positive chart width, for provider-owned resolution decisions.
Request timePolicies	Financial session policies by X-axis identity when authored; preserve actual timestamps in returned data.
Request bubbleLayers	Sample-owned combination bubble channel/axis hints; see sample layers.
Request histogram, histograms	Single/collection complete-bin requirements; see histogram source frames.
Load context signal	Cancels superseded requests and requests belonging to a detached/destroyed chart. Pass it through to fetch and check it before committing application side effects.
Response dataset, fullDomain, revision	Valid accepted detail/overview frame, stable whole-source bounds and matching generation token. A loaded window is not the full domain.

createChart({ dataSource, ...settings }) can bootstrap without a dataset/model; initial acquisition must succeed before creation resolves. An optional supplied dataset/model seeds the chart while the runtime attaches the source. Do not combine a source with row data/mapping. While attached, direct data, mapping and dataset patches reject. Use setDataSource(nextSource) to replace the owner, reloadData() to request it again, or setDataSource(undefined) to detach it. Detaching retains the last accepted dataset; row transactions still require a subsequently established row/mapping owner. Await replacements and reloads and handle rejections. Failed/stale requests retain the last accepted frame; transient loading, errors and overview are not saved in chart.model.