React ChartsKey Features

This page provides an overview of and introduction to popular features available in AG Charts. Learn how to use Community features, configure and customise themes, and get started with Enterprise features.

Displaying Data Copy

Series and Data Copy

A chart can contain multiple series, which are provided in the series array.

Every series has its own series options, but they all share a common set of configurations. These include a type as well as _Key properties to connect to the visualisation to the data, such as xKey and yKey for cartesian charts.

data: [
    {year: '2001', women: 25},
    {country: '2003', value: 26},
],
series: [
    {
        type: 'bar',
        xKey: 'year',
        yKey: 'women',
    }
]

Axes Copy

Cartesian charts can use Categorical, Numerical, Time, or Logarithmic axes. These do not need to be configured unless customisation is required.

Use axes.position to control the position of the axis, and axes.type to define the type.

axes: [
    {
        type: 'category', // category | grouped-category | number | log | time | ordinal-time
        position: 'bottom', // top | right | bottom | left
    },
    {
        type: 'number', // category | grouped-category | number | log | time | ordinal-time
        position: 'left', // top | right | bottom | left
    },
],

Polar charts such as the Radar Line Series, use Polar Axes which have similar options.

Note: All of the axes must be specified in order for these changes to take effect.

Secondary Axes Copy

Charts can have more than one axis in each direction, allowing for series with different domains to be displayed on the same chart.

Use the axes keys property to link the series _Key property to the axis.

axes: [
    // x-axis
    {
        type: 'category',
        position: 'bottom',
    },
    // primary y-axis
    {
        type: 'number',
        position: 'left',
        keys: ['women', 'men'],
    },
    // secondary y-axis
    {
        type: 'number',
        position: 'right',
        keys: ['portions'],
    },
],

Axis Intervals Copy

The Axis Interval determines which axis labels, grid lines and ticks are shown along the axis. Intervals can be defined in steps, absolute values or dynamically with min/max spacing.

Use axes.interval to control the interval of the axis.

axes: [
    {
        type: 'number',
        position: 'left',
        interval: { step: 5 }, // or { values: [0, 5, 10] } | { minSpacing: 50, maxSpacing: 100 }
    }
],

Axis Labels Copy

Axis labels can be styled, rotated and configured to automatically avoid collisions.

Use axes.label to control the appearance of the axis labels.

axes: [
    {
        type: 'number',
        position: 'left',
        label: {
            minSpacing: 20,
            avoidCollisions: false, // enabled by default
            autoRotate: false, // enabled by default
        },
    },
];

Value Formatting Copy

Data values are displayed in many places, such as series and axes labels. Use the formatter callbacks to set the format of these.

The params contain contextual information necessary to identify the item, and the callback should return a String object.

formatter: function (params) {
    return params.value * 100 + '%';
}

Data Elements Copy

Legend Copy

Legends are enabled by default on charts with more than one series.

Use the legend options to configure the legend position and size and to disable the series toggling functionality on legend click.

legend: {
    enabled: true, // defaults to true for charts with multiple series
    position: 'top', // 'bottom', 'right', 'left',
    maxWidth: 200,
    maxHeight: 300,
    toggleSeries: false
}

Cross Lines Copy

Use the crossLines array in the axis options to add line or range Cross Lines along any axis.

axes: [
    {
        crossLines: [
            {
                type: 'line',
                value: 11,
            },
            {
                type: "range",
                range: ["Jun", "Sep"],
            },
        ],
    },
],

Conditional Styling Copy

Item Stylers allow customisation of the visual appearance of series and markers based on certain conditions.

Use the itemStyler callback function to customise the appearance of a specific bar or marker:

series: [
    {
        marker: {
            itemStyler: ({ datum, xKey, fill, highlighted }) => {
                return {
                    fill: datum[xKey] === 'Jul' ? (highlighted ? 'lime' : 'red') : fill,
                };
            },
        },
    },
];

Layout and Styling Copy

Fills and Strokes Copy

Each series type has its own series specific styling options depending on the visualisation, with the most common properties being fill and stroke.

Fills can be a solid colour, a gradient or a pattern.

Strokes can have a stroke colour, as well as a strokeWidth and a lineDash[] array.

Marker Shape Copy

Markers can be customised to change their shape, size, and style.

Use the series.marker property to customise markers.

series: [
    stroke: 'maroon',
    marker: {
        shape: 'square', // defaults to 'circle'
        size: 20,
        fill: 'red',
        stroke: 'maroon',
    },
]

Themes Copy

AG Charts comes with 5 Themes, each available in light or dark mode.

Use the theme property to set the theme:

{
    theme: 'ag-default', // or 'ag-sheets', 'ag-polychrome', 'ag-material', 'ag-vivid'
}

Themes can also be customised or created with the Theming API.

Use params to set styles across the whole chart, palette to define the colour palette used for the datapoints, and overrides to change a specific default within the base theme.

const customTheme: AgChartTheme = {
    palette: {
        //these are used by each series in rotation
        fills: ['#5C2983', '#0076C5', '#21B372', '#FDDE02', '#F76700', '#D30018'],
        strokes: ['#881008'],
    },
    params: {
        // these are used by all chart elements unless explicitly overridden
        fontFamily: 'Georgia, serif',
        fontSize: 16,
    },
    overrides: {
        //used as default for all series types
        common: {
            title: {
                fontSize: 24,
            },
        },
        bar: {
            //used for bar series only
            series: {
                label: {
                    enabled: true,
                    color: 'white',
                },
            },
        },
    }
};

Chart Size Copy

The chart will dynamically auto-size to the size of its container element, defaulting to a minimum width and height of 300px.

Use the width/minWidth and height/minHeight options if a fixed size is required:

{
    width: 800,
    height: 600,
}

Interactivity Copy

Tooltips Copy

Tooltips are enabled by default. Their content is based on the data values and keys of the series.

Tooltip modes include a shared tooltip which includes the values for all series, and a compact tooltip for smaller charts.

tooltip: {
    mode: 'shared'; // or 'single' or 'compact'
}

Use the tooltip.renderer callback function to customise the content of the tooltip or create a Custom Tooltip:

{
    renderer: function (params) {
        return (
            '<div class="custom-tooltip">' +
                params.datum[params.xKey]
            '</div>'
        );
    },
},

Highlighting Hovered Data Copy

Items and Series are highlighted when hovered.

Use highlightStyles to customise highlighted items and series:

highlightStyle: {
    // Attributes that apply to individual items within a single series.
    item: {
        strokeWidth: 5,
    },
    // Attributes that apply to the entire series containing the highlighted item.
    series: {
        dimOpacity: 0.2,
    }
}

Handling Events Copy

Callbacks are provided for Series, Legend and Chart events. These include clicks, double-clicks and zoom events.

Register listeners to respond to Events on the chart.

{
    // Charts Events
    listeners: {
        click: (params) => {
            console.log('click');
        },
    },
    // Series Events
    series: [
        {
            listeners: {
                nodeClick: (params) => {
                    console.log('node clicked')
                },
            },
        },
    ],
    // Legend Events
    legend: {
        listeners: {
            legendItemClick: (params) => {
                console.log('item clicked')
            },
        },
    }
}

Saving and Restoring State Copy

The dynamic State of the chart can be saved and restored. This includes the Zoom, Annotation and Series Visibility.

Use the getState() and setState() APIs to retrieve and restore the current state of the chart.

function saveState() {
    const newState = chart.getState();
    // save to database...
}

function restoreState() {
    // retrieve state from database...
    chart.setState(state);
}

You can also use the initialState property to set the initial state of the chart when it loads.

initialState: {
    zoom: {
        rangeX: {
            start: {
                __type: 'date',
                value: new Date('2021-01-01').getTime(),
            },
        },
    },
}

Enterprise Features (e) Copy

AG Charts comes in two forms:

• AG Charts Community: Free for everyone, including production use - no licence required.
• AG Charts Enterprise: Requires a licence to use in production. Free to test locally, but requires a trial to test in production.

Import the ag-charts-enterprise package to access Enterprise features.

Learn more on the Community vs. Enterprise page.

All Enterprise features are marked with an (e) in our docs.

In the above example you can Zoom by scrolling over the chart, or by using the Navigator or Context Menu.

Zoom (e) Copy

To enable Zooming, set the zoom property to true.

zoom: {
    enabled: true,
}

See the Zoom Options for further customisation options, including enabling specific zoom methods, controlling the anchor point, scrolling step, and many more.

To allow the y-axis to automatically adjust to fit the visible items, enable the autoScaling option.

zoom: {
    autoScaling: {
        enabled: true,
    }
}

Navigator (e) Copy

Zooming and Panning can be done with the Navigator.

A Mini Chart can also be displayed within the Navigator to give additional context.

navigator: {
    enabled: true,
    miniChart: {
        enabled: true,
    },
}

Context Menu (e) Copy

The Context Menu provides Zoom and Download functionality, as well as allowing custom actions.

contextMenu: {
    enabled: true,
    extraActions: [
        { label: 'Say hello', action: () => console.log('Hello world') },
    ],
}

Annotations (e) Copy

Annotations allow end users to add trend-lines and text annotations to aid in data analysis and markup.

These are available in all Cartesian charts and can be enabled with annotations.enabled = true.

Specialized Charts (e) Copy

Financial Charts (e) Copy

Build interactive Financial Charts featuring advanced annotations with minimal configuration.

To create a financial chart, simply provide your financial data:

const [options, setOptions] = useState({
    data: getData(),
});

return (
    <AgFinancialCharts options={options} />
);

Maps (e) Copy

The Map Series types enable visualising geographic data in different ways, using GeoJSON data.

To create a map chart, provide a Map Topology in GeoJSON format and link the correct property in the properties key:

series: [
    {
        type: 'map-shape',
        topology: {
            type: 'FeatureCollection',
            features: [
                {
                    type: 'Feature',
                    geometry: {
                        type: 'Polygon',
                        coordinates: [...],
                    },
                    properties: {
                        name: 'United Kingdom',
                        code: 'GB'
                    }
                }
            ],
            // ...
        },
        data: [
            { country: 'United Kingdom', population: 67330000 },
            { country: 'France', population: 67500000 },
            // ...
        ],
        idKey: 'country',
        topologyIdKey: 'name' //default value
    }
]

Gauges (e) Copy

Radial Gauges and Linear Gauges display a single data point within a predefined range using a Radial or Linear scale.

Provide a type, value and scale to create a gauge with the createGauge API:

const [options, setOptions] = useState({
    type: 'radial-gauge', // or 'linear-gauge'
    value: 80,
    scale: {
      min: 0,
      max: 100,
    },
});

return (
    <AgGauge options={options} />
);