# Charts Technical Reference Canonical page: https://www.adaptabletools.com/docs/technical-reference-charts ## Charting State | Property | Type | Description | | --- | --- | --- | | [ChartDefinitions](https://www.adaptabletools.com/docs/reference/chartingstate.md#chartdefinitions) | [`ChartDefinition`](https://www.adaptabletools.com/docs/reference/chartdefinition.md)`[]` | Wrappers around AG Grid Chart Models | | [ExternalChartDefinitions](https://www.adaptabletools.com/docs/reference/chartingstate.md#externalchartdefinitions) | `ExternalChartDefinition[]` | Definitions of External Charts | ### Chart Definition Object | Property | Type | Description | | --- | --- | --- | | [Model](https://www.adaptabletools.com/docs/reference/chartdefinition.md#model) | `ChartModel` | AG Grid Chart Model | | [Name](https://www.adaptabletools.com/docs/reference/chartdefinition.md#name) | `string` | Unique name of the chart (used in UI and layout references, like Layout names) | | [IsReadOnly](https://www.adaptabletools.com/docs/reference/chartdefinition.md#isreadonly) | `boolean` | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full') | ------ ## Charting Options | Property | Type | Description | Default | | --- | --- | --- | --- | | [agGridContainerName](https://www.adaptabletools.com/docs/reference/chartingoptions.md#aggridcontainername) | `string` | Name shown for AG Grid's own chart window in the container list. | 'AG Grid Window' | | [chartContainers](https://www.adaptabletools.com/docs/reference/chartingoptions.md#chartcontainers) | [`ChartContainer`](https://www.adaptabletools.com/docs/reference/chartcontainer.md)`[]` | Elements a saved chart can be drawn into, offered by name when the user opens a chart.

Omit this to open charts only in AG Grid's own window. | | | [externalChartingOptions](https://www.adaptabletools.com/docs/reference/chartingoptions.md#externalchartingoptions) | [`ExternalChartingOptions`](https://www.adaptabletools.com/docs/reference/externalchartingoptions.md) | Show, hide, delete and preview for charts that are not AG Grid charts.

Required when the chart is drawn by the application. AdapTable calls these instead of opening an AG Grid chart. | | | [restoreChartsOnReady](https://www.adaptabletools.com/docs/reference/chartingoptions.md#restorechartsonready) | `boolean \| 'all' \| string[]` | Opens persisted AG Grid charts when AdapTable is ready.
- `true` or `'all'`: all charts in `Charting.ChartDefinitions`
- `string[]`: chart names to open (matches each definition's `Name` property) | undefined (no charts opened automatically) | | [saveChartBehaviour](https://www.adaptabletools.com/docs/reference/chartingoptions.md#savechartbehaviour) | [`SaveChartBehaviour`](https://www.adaptabletools.com/docs/reference/savechartbehaviour.md) | Behaviour for saving Charts: auto, manual (via popup) or none | 'none' | ### Chart Containers | Property | Type | Description | Default | | --- | --- | --- | --- | | [chartsDisplay](https://www.adaptabletools.com/docs/reference/chartcontainer.md#chartsdisplay) | `'single' \| 'multiple'` | Whether 1 or more Charts can be displayed in same location | 'single' | | [element](https://www.adaptabletools.com/docs/reference/chartcontainer.md#element) | `HTMLElement \| string` | Location - can be HTMLElement or CSS Selector | | | [name](https://www.adaptabletools.com/docs/reference/chartcontainer.md#name) | `string` | Name of Container's Location - used in Dropdowns | | ### Save Chart Behaviour [See API: savechartbehaviour](https://www.adaptabletools.com/docs/reference/savechartbehaviour.md) ### External Charting Options | Property | Type | Description | | --- | --- | --- | | [isChartOpened](https://www.adaptabletools.com/docs/reference/externalchartingoptions.md#ischartopened) | `(context: `[`ExternalChartingContext`](https://www.adaptabletools.com/docs/reference/externalchartingcontext.md)`) => boolean` | Needs to be implemented to specify if Chart is opened; used to set Show Button's highlighting | | [onDeleteChart](https://www.adaptabletools.com/docs/reference/externalchartingoptions.md#ondeletechart) | `(context: `[`ExternalChartingContext`](https://www.adaptabletools.com/docs/reference/externalchartingcontext.md)`) => void` | Called when User deletes a persisted Chart | | [onHideChart](https://www.adaptabletools.com/docs/reference/externalchartingoptions.md#onhidechart) | `(context: `[`ExternalChartingContext`](https://www.adaptabletools.com/docs/reference/externalchartingcontext.md)`) => void` | Called when User clicks on Hide button next to Chart | | [onPreviewChart](https://www.adaptabletools.com/docs/reference/externalchartingoptions.md#onpreviewchart) | `(context: `[`ExternalChartingContext`](https://www.adaptabletools.com/docs/reference/externalchartingcontext.md)`) => ExternalChartDefinition` | Shows Chart in Settings Panel preview (not saved into State); returned definition will be passed to 'onHideChart' when Preview closes | | [onShowChart](https://www.adaptabletools.com/docs/reference/externalchartingoptions.md#onshowchart) | `(context: `[`ExternalChartingContext`](https://www.adaptabletools.com/docs/reference/externalchartingcontext.md)`) => void` | Called when User clicks on Show button next to Chart | Each callback receives an [`ExternalChartingContext`](https://www.adaptabletools.com/docs/reference/externalchartingcontext.md): | Property | Type | Description | | --- | --- | --- | | [chartDefinition](https://www.adaptabletools.com/docs/reference/externalchartingcontext.md#chartdefinition) | `ExternalChartDefinition` | Definition of External Chart | | [container](https://www.adaptabletools.com/docs/reference/externalchartingcontext.md#container) | [`ChartContainer`](https://www.adaptabletools.com/docs/reference/chartcontainer.md) | Chart's Container | | [adaptableContext](https://www.adaptabletools.com/docs/reference/externalchartingcontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` | ------ ## Charting API - These functions make it easy to save and retrieves charts from [Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state/index.md) - But in practice this is more likely to be done at run-time but charts can be defined at design time if required | Method | Returns | Description | | --- | --- | --- | | [addChartDefinition(chartDefinition)](https://www.adaptabletools.com/docs/reference/chartingapi.md#addchartdefinition) | `void` | Add new Chart | | [addExternalChartDefinition(chartDef, options)](https://www.adaptabletools.com/docs/reference/chartingapi.md#addexternalchartdefinition) | `void` | Add new external chart definition | | [closeChartDefinition(chartDefinition)](https://www.adaptabletools.com/docs/reference/chartingapi.md#closechartdefinition) | `void` | Close Chart definition | | [deleteExternalChartDefinition(chartDefinition)](https://www.adaptabletools.com/docs/reference/chartingapi.md#deleteexternalchartdefinition) | `void` | Delete external chart definition | | [editChartDefinition(chartDefinition)](https://www.adaptabletools.com/docs/reference/chartingapi.md#editchartdefinition) | `void` | Edit existing Chart | | [editExternalChartDefinition(chartDef)](https://www.adaptabletools.com/docs/reference/chartingapi.md#editexternalchartdefinition) | `void` | Edit existing external chart definition | | [getChartDefinitionByName(name)](https://www.adaptabletools.com/docs/reference/chartingapi.md#getchartdefinitionbyname) | [`ChartDefinition`](https://www.adaptabletools.com/docs/reference/chartdefinition.md)` \| undefined` | Retrieves Chart definition by name | | [getChartDefinitionByUuid(uuid)](https://www.adaptabletools.com/docs/reference/chartingapi.md#getchartdefinitionbyuuid) | [`ChartDefinition`](https://www.adaptabletools.com/docs/reference/chartdefinition.md)` \| undefined` | Retrieves Chart definition by uuid | | [getChartDefinitions()](https://www.adaptabletools.com/docs/reference/chartingapi.md#getchartdefinitions) | [`ChartDefinition`](https://www.adaptabletools.com/docs/reference/chartdefinition.md)`[]` | Retrieves all adaptable Chart definitions | | [getChartingOpenState()](https://www.adaptabletools.com/docs/reference/chartingapi.md#getchartingopenstate) | [`ChartingOpenState`](https://www.adaptabletools.com/docs/reference/chartingopenstate.md) | Get info about all saved charts, incl. their open state | | [getChartRef(chartId)](https://www.adaptabletools.com/docs/reference/chartingapi.md#getchartref) | `ChartRef \| undefined` | The AG Grid chart reference for a chart AdapTable has open. | | [getCurrentChartModels()](https://www.adaptabletools.com/docs/reference/chartingapi.md#getcurrentchartmodels) | `ChartModel[]` | Retrieves current user-generated Charts | | [getExternalChartDefinitionByName(name)](https://www.adaptabletools.com/docs/reference/chartingapi.md#getexternalchartdefinitionbyname) | `ExternalChartDefinition \| undefined` | An external chart definition looked up by name. | | [getExternalChartDefinitions()](https://www.adaptabletools.com/docs/reference/chartingapi.md#getexternalchartdefinitions) | `ExternalChartDefinition[]` | Retrieves all adaptable external Chart definitions | | [getOpenChartContainer(chartDefinition)](https://www.adaptabletools.com/docs/reference/chartingapi.md#getopenchartcontainer) | [`ChartContainer`](https://www.adaptabletools.com/docs/reference/chartcontainer.md)` \| null` | Retrieve name of container in which Chart is open; returns null if Chart is not open | | [getPersistedCharts()](https://www.adaptabletools.com/docs/reference/chartingapi.md#getpersistedcharts) | `ChartModel[]` | Retrieves persisted Charts from Adaptable State | | [isChartingEnabled()](https://www.adaptabletools.com/docs/reference/chartingapi.md#ischartingenabled) | `boolean` | Whether AdapTable's Charting functionality is available | | [saveCurrentCharts()](https://www.adaptabletools.com/docs/reference/chartingapi.md#savecurrentcharts) | `void` | Saves all current Charts into Adaptable State | | [setChartEditable(chartDefinition)](https://www.adaptabletools.com/docs/reference/chartingapi.md#setcharteditable) | `void` | Make a Chart Editable (i.e. not Read-Only) | | [setChartReadOnly(chartDefinition)](https://www.adaptabletools.com/docs/reference/chartingapi.md#setchartreadonly) | `void` | Make a Chart Read-Only | | [showChartDefinition(chartDefinition, container)](https://www.adaptabletools.com/docs/reference/chartingapi.md#showchartdefinition) | `ChartRef` | Opens a Chart Definition | | [showChartDefinitionOnce(chartDefinition, container)](https://www.adaptabletools.com/docs/reference/chartingapi.md#showchartdefinitiononce) | `ChartRef \| undefined` | Displays a Chart; if Chart is already open, 2nd Chart is not opened | | [showPersistedCharts()](https://www.adaptabletools.com/docs/reference/chartingapi.md#showpersistedcharts) | `ChartRef[]` | Displays all persisted Charts | ------ ## Chart Changed Event The [Chart Changed Event](https://www.adaptabletools.com/docs/technical-reference-charts/index.md) fires whenever there are any modifications to any open [Charts](https://www.adaptabletools.com/docs/handbook-charts/index.md). ### ChartChangedInfo The event comprises a single [`ChartChangedInfo`](https://www.adaptabletools.com/docs/reference/chartchangedinfo.md) object which lists the currently opened Charts: | Property | Type | Description | | --- | --- | --- | | [chartingOpenState](https://www.adaptabletools.com/docs/reference/chartchangedinfo.md#chartingopenstate) | [`ChartingOpenState`](https://www.adaptabletools.com/docs/reference/chartingopenstate.md) | Every chart definition, with whether that chart is currently displayed. | | [adaptableContext](https://www.adaptabletools.com/docs/reference/chartchangedinfo.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` | This object contains a collection of [`ChartDisplayedInfo`](https://www.adaptabletools.com/docs/reference/chartdisplayedinfo.md) objects which contains details of displayed Charts: | Property | Type | Description | | --- | --- | --- | | [chartDefinition](https://www.adaptabletools.com/docs/reference/chartdisplayedinfo.md#chartdefinition) | [`ChartDefinition`](https://www.adaptabletools.com/docs/reference/chartdefinition.md) | Chart definition this entry describes. | | [containerName](https://www.adaptabletools.com/docs/reference/chartdisplayedinfo.md#containername) | `string \| null` | Name of the configured chart container whose element contains this chart.

Absent when the chart is closed, shown only in the AG Grid chart container, or no chart containers are configured. | | [isOpen](https://www.adaptabletools.com/docs/reference/chartdisplayedinfo.md#isopen) | `boolean` | Whether AG Grid currently has this chart open. | `chartingOpenState` is a [`ChartingOpenState`](https://www.adaptabletools.com/docs/reference/chartingopenstate.md): | Property | Type | Description | | --- | --- | --- | | [charts](https://www.adaptabletools.com/docs/reference/chartingopenstate.md#charts) | [`ChartDisplayedInfo`](https://www.adaptabletools.com/docs/reference/chartdisplayedinfo.md)`[]` | Every chart definition and its current display state. | ### Event Subscription Subscribing to the Event is done the same way as with all [Adaptable Events](https://www.adaptabletools.com/docs/technical-reference-adaptable-events/index.md): ```ts api.eventApi.on('ChartChanged', (eventInfo: ChartChangedInfo) => { // do something with the info }); ```