--- title: "Chart State" framework: angular version: "14.1.0" --- # Chart State The dynamic chart state can be saved, restored and updated at runtime. ## Save & Restore #### Saving & Restoring State ```ts // Angular entry point file import '@angular/compiler'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component'; bootstrapApplication(AppComponent); ``` [Live example: Saving & Restoring State](https://www.ag-grid.com/charts/angular/api-state/examples/legend-state-save-restore) Use the buttons to save and restore both the Legend and Zoom states. ```js 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](https://www.ag-grid.com/charts/angular/financial-charts/) also allow save, restore and update of [annotations](https://www.ag-grid.com/charts/angular/financial-charts-toolbar/) and [chart type](https://www.ag-grid.com/charts/angular/financial-charts-toolbar/#chart-type-selection). #### Saving & Restoring State ```ts // Angular entry point file import '@angular/compiler'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component'; bootstrapApplication(AppComponent); ``` [Live example: Saving & Restoring State](https://www.ag-grid.com/charts/angular/api-state/examples/state-save-restore) 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 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. #### Initial State ```ts // Angular entry point file import '@angular/compiler'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component'; bootstrapApplication(AppComponent); ``` [Live example: Initial State](https://www.ag-grid.com/charts/angular/api-state/examples/initial-state) The objects provided to this property should be the same as the object returned from the `getState()` method. ```js { 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 - `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](https://www.ag-grid.com/charts/angular/legend/#pagination). - `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](https://www.ag-grid.com/charts/angular/org-chart/). - `chartType` - This string is one of the [Chart Types](https://www.ag-grid.com/charts/angular/financial-charts-configuration/#chart-types). > **Note** > > [Data Selection](https://www.ag-grid.com/charts/angular/selection/) is not part of the chart state. See [Selection API](https://www.ag-grid.com/charts/angular/selection/#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. > **Note** > > 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 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](https://www.ag-grid.com/charts/angular/axes-types/), e.g. a date for an [Ordinal Time Axis](https://www.ag-grid.com/charts/angular/axes-types/#time). 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 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 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 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`](https://www.ag-grid.com/charts/angular/events/#item-identifiers) is derived as described in the Item Identifiers section. #### Active State ```ts // Angular entry point file import '@angular/compiler'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component'; bootstrapApplication(AppComponent); ``` [Live example: Active State](https://www.ag-grid.com/charts/angular/api-state/examples/active-save-restore) 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 The `active.frozen` property can be used to pause user interactions. #### Frozen Active State ```ts // Angular entry point file import '@angular/compiler'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component'; bootstrapApplication(AppComponent); ``` [Live example: Frozen Active State](https://www.ag-grid.com/charts/angular/api-state/examples/frozen-active-state) 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 The `collapsed` state stores the identifiers of items collapsed in an [Org Chart](https://www.ag-grid.com/charts/angular/org-chart/). Changes to this state can be listened to with the `collapsedChange` event. See the [Events API](https://www.ag-grid.com/charts/angular/events/#collapsedchange) page for more details. ## API Reference #### AgChartInstance | Property | Type | Default | Description | | --- | --- | --- | --- | | getState | Function | | Returns a representation of the current state of the given `AgChartInstance`. | | setState | Function | | Sets the state of the given `AgChartInstance` to the state provided. | #### InitialState | Property | Type | Default | Description | | --- | --- | --- | --- | | active | AgActiveState | | The initial picked item. | | active.activeItem | AgActiveItemState | | The active series datum shape. If the entire series is active, then `itemId` will be set to `undefined`. | | active.activeItem.type (required) | 'series-node' \| 'legend' | | Where the item activation originates from. | | active.activeItem.seriesId (required) | string | | The unique identifier of the series that this picked datum belongs to. | | active.activeItem.itemId (required) | string \| number | | The unique identifier of the picked datum. | | active.frozen | boolean | | The frozen state. When the picked item is frozen, user interactions with the chart will be ignored and not updated the currently picked item. | | annotations | AgAnnotation[] | | The initial set of annotations to display on the chart. | | chartType | AgInitialStateChartType | | The initial chart type. | | collapsed | Array | | The initial collapsed datums by id, for Organization Charts. | | legend | AgInitialStateLegendOptions[] | | The initial legend series visibility state. | | legend.visible (required) | boolean | | Whether the legend item is currently enabled or not. | | legend.seriesId | string | | Series or item id | | legend.itemId | string | | Legend item id - usually yKey value for cartesian series. | | legend.legendItemName | string | | Human-readable description of the y-values. If supplied, matching items with the same value will be toggled together. | | legendPagination | number | | The initial legend pagination page as a zero-based index, restored on a best-effort like-for-like basis as the page count depends on the render size. | | zoom | AgInitialStateZoomOptions | | The initial zoom state. | | zoom.rangeX | AgInitialStateZoomRange | | The initial zoom range for the x-axis. | | zoom.rangeX.start | AgStateSerializableDate \| AgStateSerializableBigInt \| AgStateSerializableGroupingValueType \| number | | The start value of the zoom range. A number, or a serialised value object. | | zoom.rangeX.end | AgStateSerializableDate \| AgStateSerializableBigInt \| AgStateSerializableGroupingValueType \| number | | The end value of the zoom range. A number, or a serialised value object. | | zoom.rangeY | AgInitialStateZoomRange | | The initial zoom range for the y-axis. | | zoom.rangeY.start | AgStateSerializableDate \| AgStateSerializableBigInt \| AgStateSerializableGroupingValueType \| number | | The start value of the zoom range. A number, or a serialised value object. | | zoom.rangeY.end | AgStateSerializableDate \| AgStateSerializableBigInt \| AgStateSerializableGroupingValueType \| number | | The end value of the zoom range. A number, or a serialised value object. | | zoom.ratioX | AgInitialStateZoomRatio | | The initial zoom ratio for the x-axis. | | zoom.ratioX.start | Ratio | | The start ratio of the zoom range. | | zoom.ratioX.end | Ratio | | The end ratio of the zoom range. | | zoom.ratioY | AgInitialStateZoomRatio | | The initial zoom ratio for the y-axis. | | zoom.ratioY.start | Ratio | | The start ratio of the zoom range. | | zoom.ratioY.end | Ratio | | The end ratio of the zoom range. | | zoom.autoScaledAxes | AgAutoScaledAxes | | Axes that are zoomed by the auto scaling functionality. |