---
title: "Data Configuration and Update"
framework: react
version: "14.1.0"
---

# Data 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

### Data Structure

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

```js
{
    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](https://www.ag-grid.com/charts/react/ts-generics/) support enables compile-time checks and auto-complete for the elements of the `data[]` property.
- Hierarchical Series such as [Treemap](https://www.ag-grid.com/charts/react/treemap-series/) and [Sunburst](https://www.ag-grid.com/charts/react/sunburst-series/) use a `children` array to represent nested levels.

### Binding Data To Series

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.

#### Using Data Example

```tsx
import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgChartOptions,
  BarSeriesModule,
  CategoryAxisModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";

ModuleRegistry.registerModules([
  BarSeriesModule,
  CategoryAxisModule,
  LegendModule,
  NumberAxisModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    title: { text: "Annual Attendees by Gender" },
    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",
      },
    ],
  });

  return <AgCharts options={options} />;
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Using Data Example](https://www.ag-grid.com/charts/reactFunctionalTs/data-configuration/examples/basic-data)

```js
{
    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](https://www.ag-grid.com/charts/options/#reference-AgChartOptions-series) for more details.

### Per-Series Data

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.

```js
{
    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

The following formats are accepted for each type of value.

### Time

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](https://en.wikipedia.org/wiki/ISO_8601) date or date-time string.

```js
{
    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](https://www.ag-grid.com/charts/react/axes-types/#time).

### Numbers

Numeric values may be supplied as:

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

```js
{
    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](https://www.ag-grid.com/charts/react/axes-types/#number) and [Log](https://www.ag-grid.com/charts/react/axes-types/#log) axes, and used by colour and size scales.

### Categories

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

Category values are displayed on [Category Axes](https://www.ag-grid.com/charts/react/axes-types/#category).

## Field Dot Notation

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.

```js
{
    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

After chart creation, data can be updated by mutating the data object.

For details on update methods, see the [Create/Update API Reference](https://www.ag-grid.com/charts/react/api-create-update/).

### High Frequency Updates

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.

```js
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](https://www.ag-grid.com/charts/react/transactions/) for details.

For details on transaction operations, see [High-Frequency Data](https://www.ag-grid.com/charts/react/high-frequency-data/).