JavaScript ChartsData Configuration and Update

This page describes how to provide data to be visualised by AG Charts, and how to update it.

Data Structure and Binding Copy Link

Data Structure Copy Link

AG Charts expects data as an array of objects, where each object represents a data point.

{
    data: [
        { year: '2021', sales: 50000, profit: 15000 },
        { year: '2022', sales: 65000, profit: 22000 },
        { year: '2023', sales: 78000, profit: 28000 },
    ],
}

• The data can be any array of objects, with properties being mapped to chart elements like axes, size, and colour.
• TypeScript Generics support enables compile-time checks and auto-complete for the elements of the data[] property.
• Hierarchical Series such as Treemap and Sunburst use a children array to represent nested levels.

Binding Data To Series Copy Link

Every series in a chart has _Key properties for connecting the visualisation elements to the data fields.

These properties include xKey and yKey for cartesian charts, colorKey for heatmap and angleKey for pie series.

{
    data: [
        { year: '2021', women: 25, men: 20 },
        { year: '2022', women: 28, men: 22 },
        { year: '2023', women: 32, men: 24 },
    ],
    series: [
        {
            type: 'bar',
            xKey: 'year',
            yKey: 'women',
            yName: 'Women',
        },
        {
            type: 'bar',
            xKey: 'year',
            yKey: 'men',
            yName: 'Men',
        },
    ],
}

In this example:

• The data array contains the data for all series in the chart.
• Series 1 visualises the women field on the y-axis using yKey: 'women'.
• Series 2 visualises the men field on the y-axis using yKey: 'men'.
• The xKey: 'year' is used by both series, determining the x-axis categories.

The _Key properties vary by series type - see the Series Options for more details.

Per-Series Data Copy Link

All series use the root-level data option by default, and this approach is recommended for best performance. However, to support scenarios where different data sources are needed, each individual series can declare its own data option.

{
    series: [
        {
            type: 'bar',
            data: [
                { year: '2021', women: 25 },
                { year: '2022', women: 28 },
                { year: '2023', women: 32 },
            ],
            xKey: 'year',
            yKey: 'women',
            yName: 'Women',
        },
        {
            type: 'bar',
            data: [
                { year: '2021', men: 20 },
                { year: '2022', men: 22 },
                { year: '2023', men: 24 },
            ],
            xKey: 'year',
            yKey: 'men',
            yName: 'Men',
        },
    ],
}

When a series specifies its own data array, it overrides the root-level data option for that series only. Other series continue to use root-level data.

Data Types Copy Link

The following formats are accepted for each type of value.

Time Copy Link

Time values may be supplied as:

• A JavaScript Date object.
• A numeric Unix epoch, in milliseconds since 1 January 1970 (UTC).
• A bigint Unix epoch, for values beyond the safe range of number (2⁵³ − 1).
• An ISO 8601 date or date-time string.

{
    data: [
        { time: new Date(2023, 0, 1), value: 50 }, // JavaScript Date
        { time: 1672531200000, value: 65 }, // Unix epoch (milliseconds)
        { time: '2023-02-01', value: 78 }, // ISO 8601 date
        { time: '2023-02-01T14:30:00Z', value: 90 }, // ISO 8601 date-time
    ],
}

Time values are displayed on Time Axes.

Numbers Copy Link

Numeric values may be supplied as:

• A number, for integers and decimals.
• A bigint, for integers beyond the safe range of number (2⁵³ − 1).

{
    data: [
        { id: 'a', count: 1500 }, // number
        { id: 'b', count: 9007199254740993n }, // bigint
    ],
}

If a field mixes number and bigint values, AG Charts logs a warning and narrows the bigint values to number, which may lose precision beyond ±(2⁵³ − 1). Keep to one numeric type per field.

Numeric values are displayed on Number and Log axes, and used by colour and size scales.

Categories Copy Link

Category values may be any type. Strings are used directly; other values are converted with toString().

Category values are displayed on Category Axes.

Field Dot Notation Copy Link

By default, AG Charts supports dot notation for accessing nested properties in your data.

Use the suppressFieldDotNotation option to disable this feature if your field names contain the . character.

{
    data: [
        { user: { name: 'Alice', age: 30 } },
        { user: { name: 'Bob', age: 25 } },
    ],
    series: [
        {
            type: 'bar',
            xKey: 'user.name', // Accesses nested property
            yKey: 'user.age',
        },
    ],
}

Updating Data Copy Link

After chart creation, data can be updated by calling the AgChartInstance.update() or AgChartInstance.updateDelta() with a new data array.

chart.updateDelta({
    data: newData,
});

For details on update methods, see the Create/Update API Reference.

High Frequency Updates Copy Link

For high-frequency or streaming data, use applyTransaction() to update specific items without replacing the entire dataset. This is significantly faster for small changes to large datasets.

chart.applyTransaction({
    add: [{ date: new Date(), value: 42 }],
    remove: [oldDataPoint],
    update: [{ ...updatedDataPoint }],
});

Set dataIdKey on the chart options to identify items by a unique field instead of by object reference. See Transactions for details.

For details on transaction operations, see High-Frequency Data.