AG Studio Launch Week šŸš€šŸš€šŸš€ 28 Sep - 2 Oct 2026 šŸš€šŸš€šŸš€ Join now
AG Grid
Best JavaScript Grid in the World
AG Charts
Best JavaScript Charts in the World
AG Studio
Best JavaScript Dashboard in the World
Bryntum Gantt
Speed-tuned Gantt chart for project planning
Bryntum Scheduler
Resource scheduling timeline component
PROPRO
Bryntum Scheduler Pro
Scheduler with auto-scheduling and constraints
Bryntum Calendar
Flexible JavaScript event calendar
Bryntum Task Board
Kanban-style task board component
Search

JavaScript ChartsChart State

Version 14.1.0

The dynamic chart state can be saved, restored and updated at runtime.

Save & Restore Copy Link

Use the buttons to save and restore both the Legend and Zoom states.

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

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

In the above example:

  • Zoom and pan the chart, and also toggle some legend items. Then click 'Save' to store the chart state using chart.getState().
  • Click the 'Restore' button to restore a saved state to the chart using chart.setState().
  • This will override the current state.

Financial Charts also allow save, restore and update of annotations and chart type.

In the above example:

  • Use the toolbar to create annotations and change the chart type, and then click 'Save' to store the chart state using chart.getState().
  • Click the 'Restore' button to restore a saved state to the chart using chart.setState().
  • This will override the current state.

Initial State Copy Link

The initialState chart option allows creating a chart with a saved state already applied.

Additionally, mutating this option at runtime will modify the chart state dynamically.

The objects provided to this property should be the same as the object returned from the getState() method.

{
    initialState: {
        zoom: {
            rangeX: {
                start: {
                    __type: 'date',
                    value: new Date('2021-01-01').getTime(),
                },
            },
        },
        legend: [
            {
                seriesId: 'tate-modern',
                visible: false,
            },
        ],
    },
}

In this example:

  • The chart loads with an initialState for both Zoom and Legend.
  • Clicking the buttons updates the initialState, changing the Zoom or Legend toggle state.
  • Note that the same approach applies to Financial Charts.

State Contents Copy Link

  • zoom - This object contains start and end ranges of the zoom.
  • legend - This array contains the current visibility of each series or item in the legend.
  • legendPagination - This number is the current legend page of a paginated legend.
  • active - This object contains the currently active item, which is the series node or legend item that is highlighted/showing a tooltip.
  • annotations - This object contains the position and style of any displayed drawings or text annotations.
  • collapsed - This array contains the identifiers of the currently collapsed items in an Org Chart.
  • chartType - This string is one of the Chart Types.

Data Selection is not part of the chart state. See Selection API more details.

Note that all the state properties are optional, so a property can be excluded if you do not want to restore it.

Date objects cannot be serialised, so should instead be provided as an AgStateSerializableDate object in the format { __type: 'date', value: string | number } with a value of any date string or a timestamp number.

Dates returned from chart.getState() will be in the ISO-8601 format and UTC timezone.

Zoom Copy Link

Zoom state can be provided as a range or ratio on each axis direction with either the rangeX & rangeY or ratioX & ratioY properties.

If both a range and ratio are provided, only the rangeX and rangeY values will be used.

The start and end properties of rangeX and rangeY should match the type of axis, e.g. a date for an Ordinal Time Axis.

The start and end properties of ratioX and ratioY should be a value between 0 and 1 as a proportion of the width or height of the chart.

Legend Copy Link

The initial legend state can be configured with an array of objects defining legend items for the series in the chart. Each object includes a seriesId to match the series and a visible property to control its visibility.

For series with multiple legend items, such as pie or donut, an itemId specifies data elements by their index in the data array.

A legendItemName can be added to the legend initial state and series options, taking priority over both seriesId and itemId.

Legend Pagination Copy Link

The legendPagination state stores the current legend page as a zero-based index.

If the saved page does not exist due to a change in chart size or legend configuration, it is clamped to the last available page.

Active Copy Link

The active state gives programmatic control over chart highlighting and tooltips, as well as saving and restoring the active state.

The active item's itemId is derived as described in the Item Identifiers section.

In this example:

  • Click a bar or legend item to store the chart state using chart.getState().
  • Click the 'Restore' button to restore the saved state to the chart using chart.setState().
  • This will make the same item active again, showing its tooltip and highlight.

Frozen Active Copy Link

The active.frozen property can be used to pause user interactions.

In this example:

  • Clicking the chart freezes the current Active State. The Highlight & Tooltip remain static when the mouse moves.
  • Clicking the 'Unfreeze' button in the Tooltip restores interactivity.

Collapsed Copy Link

The collapsed state stores the identifiers of items collapsed in an Org Chart.

Changes to this state can be listened to with the collapsedChange event. See the Events API page for more details.

API Reference Copy Link