The AgChartOptions interface is the gateway to creating charts.
An instance of AgChartOptions is an essential configuration object required to create a chart with the desired data and attributes.
To initialise a chart, an instance of the AgChartOptions is passed to the AgChart.create() factory method. Once the chart is initialised, it can be modified using the AgChart.update() method.
Options by Chart Type
Properties, formatters and event handlers are all available through the AgChartOptions interface. Specifying these on the options object will enable fine grained control of charts including registering event listeners and applying styles to individual data points.
The AgChartOptions interface is displayed below in an expandable JSON graph, which can be navigated to explore the object structure.
Click through the tabs to see the three main variations of AgChartOptions depending on the chart/series type to be rendered.
Creating and Updating Charts Using Complete Options
AgChart exposes create() and update() static methods to perform chart initialisation and update respectively.
Mutations to the previously used options object are not automatically picked up by the chart implementation,
AgChart.update() should be called for changes to be applied.
NOTE: We expect the options supplied to AgChart.update() to be the full configuration to update
to, not a partial configuration. Use AgChart.updateDelta() to apply partial updates.
The following example demonstrates both create and update cases:
Definition of an options object used to create the initial chart state.
Buttons that invoke mutations of the options and trigger update of the chart state.
AgChart exposes an updateDelta() static method to allow partial updates to an existing charts configuration.
To assist with state management, the complete applied options state can be retrieved by calling getOptions() on the
chart instance.
Update an existing AgChartInstance. Options provided should be complete and not partial. NOTE: As each call could trigger a chart redraw, multiple calls to update options in quick succession could result in undesirable flickering, so callers should batch up and/or debounce changes to avoid unintended partial update renderings.
Update an existing AgChartInstance by applying a partial set of option changes. NOTE: As each call could trigger a chart redraw, each individual delta options update should leave the chart in a valid options state. Also, multiple calls to update options in quick succession could result in undesirable flickering, so callers should batch up and/or debounce changes to avoid unintended partial update renderings.
Properties available on the AgChartInstance interface.
getOptions
Function
Get the AgChartOptions representing the current chart configuration.
getOptions = () => AgChartOptions;
type AgChartOptions =
AgCartesianChartOptions
| AgPolarChartOptions
| AgHierarchyChartOptions
interface AgHierarchyChartOptions {
// Type of chart to render. Inherited from the first declared series if unspecified.
type?: 'hierarchy' | 'treemap';
// The data to render the chart from. If this is not specified, it must be set on individual series instead.
data?: any;
// Series configurations.
series?: AgHierarchySeriesOptions[];
// The element to place the rendered chart into.<br/><strong>Important: make sure to read the `autoSize` config description for information on how the container element affects the chart size (by default).
container?: HTMLElement | null;
// The width of the chart in pixels. Has no effect if `autoSize` is set to `true`.
width?: PixelSize;
// The height of the chart in pixels. Has no effect if `autoSize` is set to `true`.
height?: PixelSize;
// By default, the chart will resize automatically to fill the container element. Set this to `false` to disable this behaviour. If either the `width` or `height` are set, auto-sizing will be disabled unless this is explicitly set to `true`.<br/><strong>Important: if this config is set to `true`, make sure to give the chart's `container` element an explicit size, otherwise you will run into a chicken and egg situation where the container expects to size itself according to the content and the chart expects to size itself according to the container.
autoSize?: boolean;
// Configuration for the padding shown around the chart.
padding?: AgChartPaddingOptions;
// Configuration for the background shown behind the chart.
background?: AgChartBackground;
// Configuration for the title shown at the top of the chart.
title?: AgChartCaptionOptions;
// Configuration for the subtitle shown beneath the chart title. Note: a subtitle will only be shown if a title is also present.
subtitle?: AgChartCaptionOptions;
// Global configuration that applies to all tooltips in the chart.
tooltip?: AgChartTooltipOptions;
// Configuration for the chart legend.
legend?: AgChartLegendOptions;
// A map of event names to event listeners.
listeners?: AgBaseChartListeners;
// Theme to use for rendering of the chart. Specify an inbuilt theme name, or provide an `AgChartTheme` instance to customise.
theme?: string | AgChartTheme;
}
type AgHierarchySeriesOptions =
AgTreemapSeriesOptions
interface AgTreemapSeriesOptions<DatumType = any> {
type?: 'treemap';
// The label configuration for the top-level tiles.
title?: AgTreemapSeriesLabelOptions;
// The label configuration for the children of the top-level parent tiles.
subtitle?: AgTreemapSeriesLabelOptions;
// Configuration for the tile labels.
labels?: AgTreemapSeriesLabelsOptions;
// The name of the node key containing the label.
labelKey?: string;
// The name of the node key containing the size value.
sizeKey?: string;
// The name of the node key containing the color value. This value (along with `colorDomain` and `colorRange` configs) will be used to determine the tile color.
colorKey?: string;
// The domain the 'colorKey' values belong to. The domain can contain more than two stops, for example `[-5, 0, -5]`. In that case the 'colorRange' should also use a matching number of colors.
colorDomain?: number[];
// The color range to interpolate the numeric `colorDomain` into. For example, if the `colorDomain` is `[-5, 5]` and `colorRange` is `['red', 'green']`, a `colorKey` value of `-5` will be assigned the 'red' color, `5` - 'green' color and `0` a blend of 'red' and 'green'.
colorRange?: string[];
// The group fill color. If undefined the value based on `colorKey` will be used.
groupFill?: string;
// The group's stroke color.
groupStroke?: string;
// The group's stroke width.
groupStrokeWidth?: number;
// The tile's stroke color.
tileStroke?: string;
// The tile's stroke width.
tileStrokeWidth?: number;
// Series-specific tooltip configuration.
tooltip?: AgTreemapSeriesTooltip<DatumType>;
// The amount of padding in pixels inside of each treemap tile. Increasing `nodePadding` will reserve more space for parent labels.
nodePadding?: PixelSize;
// Whether or not to use gradients for treemap tiles.
gradient?: boolean;
// Configuration for the shadow used behind the treemap tiles.
tileShadow?: AgDropShadowOptions;
// Configuration for the shadow used behind the treemap labels.
labelShadow?: AgDropShadowOptions;
// Determines whether the groups will be highlighted by cursor.
highlightGroups?: boolean;
// Configuration for treemap tiles when they are hovered over.
highlightStyle?: AgTreemapSeriesHighlightStyle;
// A callback function for adjusting the styles of a particular treemap tile based on the input parameters
formatter?: (params: AgTreemapSeriesFormatterParams<DataValue>) => AgTreemapSeriesFormat;
// A map of event names to event listeners.
listeners?: AgSeriesListeners<DatumType>;
// Primary identifier for the series. This is provided as `seriesId` in user callbacks to differentiate multiple
// series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour
// by series please supply your own unique `id` value.
//
// Default: auto-generated value
id?: string;
// The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
data?: DatumType[];
// Whether or not to display the series.
visible?: boolean;
// Whether or not to include the series in the legend.
showInLegend?: boolean;
// The cursor to use for hovered area markers. This config is identical to the CSS `cursor` property.
cursor?: string;
}
interface AgTreemapSeriesLabelOptions {
// The amount of the tile's vertical space to reserve for the label.
padding?: number;
// Whether or not the labels should be shown.
enabled?: boolean;
// The font style to use for the labels.
fontStyle?: FontStyle;
// The font weight to use for the labels.
fontWeight?: FontWeight;
// The font size in pixels to use for the labels.
fontSize?: FontSize;
// The font family to use for the labels.
fontFamily?: FontFamily;
// The colour to use for the labels.
color?: CssColor;
}
type FontStyle =
'normal'
| 'italic'
| 'oblique'
type FontWeight =
'normal'
| 'bold'
| 'bolder'
| 'lighter'
| '100'
| '200'
| '300'
| '400'
| '500'
| '600'
| '700'
| '800'
| '900'
type FontSize = number
type FontFamily = string
type CssColor = string
interface AgTreemapSeriesLabelsOptions {
// The label configuration for the large leaf tiles.
large?: AgChartLabelOptions;
// The label configuration for the medium-sized leaf tiles.
medium?: AgChartLabelOptions;
// The label configuration for the small leaf tiles.
small?: AgChartLabelOptions;
// The configuration for the cell value label.
value?: { key?: string; name?: string; formatter?: (params: { datum: any; }) => string | undefined; style?: AgChartLabelOptions; };
}
interface AgChartLabelOptions {
// Whether or not the labels should be shown.
enabled?: boolean;
// The font style to use for the labels.
fontStyle?: FontStyle;
// The font weight to use for the labels.
fontWeight?: FontWeight;
// The font size in pixels to use for the labels.
fontSize?: FontSize;
// The font family to use for the labels.
fontFamily?: FontFamily;
// The colour to use for the labels.
color?: CssColor;
}
interface AgTreemapSeriesTooltip<DatumType> {
// Function used to create the content for tooltips.
renderer?: (params: AgTreemapSeriesTooltipRendererParams<DatumType>) => string | AgTooltipRendererResult;
// Whether or not to show tooltips when the series are hovered over.
enabled?: boolean;
}
interface AgTreemapSeriesTooltipRendererParams<DatumType> {
// Datum from the series data that the treemap tile is being rendered for.
datum: DatumType;
// The parent of the datum from the treemap data.
parent?: DataValue;
// The depth of the datum in the hierarchy.
depth: number;
// sizeKey as specified on series options.
sizeKey?: string;
// labelKey as specified on series options.
labelKey?: string;
// colorKey as specified on series options.
colorKey?: string;
// The computed fill colour of the treemap tile.
color?: string;
// The title of the treemap tile
title?: string;
// The ID of the series.
seriesId: string;
}
type DataValue = any
interface AgTooltipRendererResult {
// Title text for the tooltip header.
title?: string;
// Content text for the tooltip body.
content?: string;
// Tooltip title text color.
color?: string;
// Tooltip title background color.
backgroundColor?: string;
}
type PixelSize = number
interface AgDropShadowOptions {
// Whether or not the shadow is visible.
enabled?: boolean;
// The colour of the shadow.
color?: CssColor;
// The horizontal offset in pixels for the shadow.
xOffset?: PixelSize;
// The vertical offset in pixels for the shadow.
yOffset?: PixelSize;
// The radius of the shadow's blur, given in pixels.
blur?: PixelSize;
}
interface AgTreemapSeriesHighlightStyle {
// Highlight style used for a text when item is tapped or hovered over.
text?: AgTreemapSeriesHighlightTextStyle;
// Highlight style used for an individual marker when tapped or hovered over.
item?: AgSeriesHighlightMarkerStyle;
// Highlight style used for whole series when one of its markers is tapped or hovered over.
series?: AgSeriesHighlightSeriesStyle;
}
interface AgTreemapSeriesHighlightTextStyle {
// The colour of an item's text when tapped or hovered over. Use `undefined` for no highlight.
color?: CssColor;
}
interface AgSeriesHighlightMarkerStyle {
// The fill colour of a marker when tapped or hovered over. Use `undefined` for no highlight.
fill?: CssColor;
// The opacity of the fill for the highlighted item.
fillOpacity?: Opacity;
// The stroke colour of a marker when tapped or hovered over. Use `undefined` for no highlight.
stroke?: CssColor;
// The stroke width of a marker when tapped or hovered over. Use `undefined` for no highlight.
strokeWidth?: PixelSize;
}
type Opacity = number
interface AgSeriesHighlightSeriesStyle {
enabled?: boolean;
// The opacity of the whole series (area line, area fill, labels and markers, if any) when another chart series or another stack level in the same area series is highlighted by hovering a data point or a legend item. Use `undefined` or `1` for no dimming.
dimOpacity?: Opacity;
// The stroke width of the area line when one of the markers is tapped or hovered over, or when a tooltip is shown for a data point, even when series markers are disabled. Use `undefined` for no highlight.
strokeWidth?: PixelSize;
}
interface AgTreemapSeriesFormatterParams<DataValue = any> {
// Datum from the series data that the treemap tile is being rendered for.
datum: DataValue;
// The parent of the datum from the treemap data.
parent?: DataValue;
// The depth of the datum in the hierarchy.
depth: number;
// labelKey as specified on series options.
labelKey: string;
// sizeKey as specified on series options.
sizeKey?: string;
// colorKey as specified on series options.
colorKey?: string;
// The colour of the fill for the treemap tile.
fill?: CssColor;
// The opacity of the fill for the treemap tile.
fillOpacity?: Opacity;
// The colour of the stroke for the treemap tile.
stroke?: CssColor;
// The opacity of the stroke for the treemap tile.
strokeOpacity?: Opacity;
// The width in pixels of the stroke for the treemap tile.
strokeWidth?: PixelSize;
// Whether or not the gradients are used for treemap tiles.
gradient?: boolean;
// `true` if the tile is highlighted by hovering
highlighted: boolean;
// The ID of the series.
seriesId: string;
}
interface AgTreemapSeriesFormat {
// The colour of the fill for the treemap tile.
fill?: CssColor;
// The opacity of the fill for the treemap tile.
fillOpacity?: Opacity;
// The colour of the stroke for the treemap tile.
stroke?: CssColor;
// The opacity of the stroke for the treemap tile.
strokeOpacity?: Opacity;
// The width in pixels of the stroke for the treemap tile.
strokeWidth?: PixelSize;
// Whether or not the gradient is used for the treemap tile.
gradient?: boolean;
}
interface AgSeriesListeners<DatumType> {
// The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is clicked.
nodeClick: (params: AgSeriesNodeClickParams<DatumType>) => void;
}
interface AgSeriesNodeClickParams<DatumType> {
// Event type.
type: 'nodeClick';
// Series ID, as specified in series.id (or generated if not specified)
seriesId: string;
// Datum from the series data array.
datum: DatumType;
// xKey as specified on series options
xKey?: string;
// yKey as specified on series options
yKey?: string;
// sizeKey as specified on series options
sizeKey?: string;
// labelKey as specified on series options
labelKey?: string;
// colorKey as specified on series options
colorKey?: string;
// angleKey as specified on series options
angleKey?: string;
// calloutLabelKey as specified on series options
calloutLabelKey?: string;
// sectorLabelKey as specified on series options
sectorLabelKey?: string;
// radiusKey as specified on series options
radiusKey?: string;
}
interface AgChartPaddingOptions {
// The number of pixels of padding at the top of the chart area.
top?: PixelSize;
// The number of pixels of padding at the right of the chart area.
right?: PixelSize;
// The number of pixels of padding at the bottom of the chart area.
bottom?: PixelSize;
// The number of pixels of padding at the left of the chart area.
left?: PixelSize;
}
interface AgChartBackground {
// Whether or not the background should be visible.
visible?: boolean;
// Colour of the chart background.
fill?: CssColor;
}
interface AgChartCaptionOptions {
// Whether or not the title should be shown.
enabled?: boolean;
// The text to show in the title.
text?: string;
// The font style to use for the title.
fontStyle?: FontStyle;
// The font weight to use for the title.
fontWeight?: FontWeight;
// The font size in pixels to use for the title.
fontSize?: FontSize;
// The font family to use for the title.
fontFamily?: FontFamily;
// The colour to use for the title.
color?: CssColor;
// Spacing added to help position the caption. Default: 20
spacing?: number;
}
interface AgChartTooltipOptions {
// Set to false to disable tooltips for all series in the chart.
enabled?: boolean;
// A class name to be added to the tooltip element of the chart.
class?: string;
// If true, for series with markers the tooltip will be shown to the closest marker.
tracking?: boolean;
// The time interval (in milliseconds) after which the tooltip is shown.
delay?: number;
}
interface AgChartLegendOptions {
// Whether or not to show the legend.
enabled?: boolean;
// Where the legend should show in relation to the chart.
position?: AgChartLegendPosition;
// How the legend items should be arranged.
orientation?: AgChartOrientation;
// Used to constrain the width of the legend.
maxWidth?: PixelSize;
// Used to constrain the height of the legend.
maxHeight?: PixelSize;
// The spacing in pixels to use outside the legend.
spacing?: PixelSize;
// Configuration for the legend items that consist of a marker and a label.
item?: AgChartLegendItemOptions;
// Reverse the display order of legend items if `true`.
reverseOrder?: boolean;
// Optional callbacks for specific legend-related events.
listeners?: AgChartLegendListeners;
pagination?: AgChartLegendPaginationOptions;
}
type AgChartLegendPosition =
'top'
| 'right'
| 'bottom'
| 'left'
type AgChartOrientation =
'horizontal'
| 'vertical'
interface AgChartLegendItemOptions {
// Configuration for the legend markers.
marker?: AgChartLegendMarkerOptions;
// Configuration for the legend labels.
label?: AgChartLegendLabelOptions;
// Used to constrain the width of legend items.
maxWidth?: PixelSize;
// The horizontal spacing in pixels to use between legend items.
paddingX?: PixelSize;
// The vertical spacing in pixels to use between legend items.
paddingY?: PixelSize;
// Set to `false` to turn off toggling of the series visibility in the chart when the legend item is clicked.
toggleSeriesVisible?: boolean;
}
interface AgChartLegendMarkerOptions {
// The size in pixels of the markers in the legend.
size?: PixelSize;
// If set, overrides the marker shape from the series and the legend will show the specified marker shape instead. If not set, will use a marker shape matching the shape from the series, or fall back to `'square'` if there is none.
shape?: MarkerShape;
// The padding in pixels between a legend marker and the corresponding label.
padding?: PixelSize;
// The width in pixels of the stroke for markers in the legend.
strokeWidth?: PixelSize;
}
type MarkerShape =
'circle'
| 'cross'
| 'diamond'
| 'heart'
| 'plus'
| 'triangle'
| any
interface AgChartLegendLabelOptions {
// If the label text exceeds the maximum length, it will be truncated and an ellipsis will be appended to indicate this.
maxLength?: number;
// The colour of the text.
color?: CssColor;
// The font style to use for the legend.
fontStyle?: FontStyle;
// The font weight to use for the legend.
fontWeight?: FontWeight;
// The font size in pixels to use for the legend.
fontSize?: FontSize;
// The font family to use for the legend.
fontFamily?: FontFamily;
// Function used to render legend labels. Where `id` is a series ID, `itemId` is component ID within a series, such as a field name or an item index.
formatter?: (params: AgChartLegendLabelFormatterParams) => string;
}
interface AgChartLegendLabelFormatterParams {
seriesId: string;
itemId: any;
value: string;
}
interface AgChartLegendListeners {
// The listener to call when a legend item is clicked.
legendItemClick?: (event: AgChartLegendClickEvent) => void;
}
interface AgChartLegendClickEvent {
// Series id
seriesId: string;
// Legend item id - usually yKey value for cartesian series.
itemId: string;
// Whether the legend item is currently enabled or not.
enabled: boolean;
}
interface AgChartLegendPaginationOptions {
// Configuration for the pagination markers.
marker?: AgPaginationMarkerOptions;
// Configuration for pagination buttons when a button is active.
activeStyle?: AgPaginationMarkerStyle;
// Configuration for pagination buttons when a button is inactive.
inactiveStyle?: AgPaginationMarkerStyle;
// Configuration for pagination buttons when a button is hovered over.
highlightStyle?: AgPaginationMarkerStyle;
// Configuration for the pagination label.
label?: AgPaginationLabelOptions;
}
interface AgPaginationMarkerOptions {
// The size in pixels of the pagination buttons.
size?: PixelSize;
// If set, overrides the marker shape for the pagination buttons. If not set, the pagination buttons will default to the `'triangle'` marker shape.
shape?: MarkerShape;
// The inner padding in pixels between a pagination button and the pagination label.
padding?: PixelSize;
}
interface AgPaginationMarkerStyle {
// The fill colour to use for the pagination button markers.
fill?: CssColor;
// Opacity of the pagination buttons.
fillOpacity?: Opacity;
// The colour to use for the button strokes.
stroke?: CssColor;
// The width in pixels of the button strokes.
strokeWidth?: PixelSize;
// Opacity of the button strokes.
strokeOpacity?: Opacity;
}
interface AgPaginationLabelOptions {
// The colour of the text.
color?: CssColor;
// The font style to use for the pagination label.
fontStyle?: FontStyle;
// The font weight to use for the pagination label.
fontWeight?: FontWeight;
// The font size in pixels to use for the pagination label.
fontSize?: FontSize;
// The font family to use for the pagination label.
fontFamily?: FontFamily;
}
interface AgBaseChartListeners {
// The listener to call when a node (marker, column, bar, tile or a pie sector) in any series is clicked. In case a chart has multiple series, the chart's `seriesNodeClick` event can be used to listen to `nodeClick` events of all the series at once.
seriesNodeClick?: (event: AgNodeClickEvent) => any;
// The listener to call to signify a general click on the chart by the user.
click?: (event: AgChartClickEvent) => any;
}
interface AgNodeClickEvent {
// Event type.
type: 'seriesNodeClick';
// Series ID, as specified in series.id (or generated if not specified)
seriesId: string;
// Datum from the chart or series data array.
datum: any;
// xKey as specified on series options
xKey?: string;
// yKey as specified on series options
yKey?: string;
// sizeKey as specified on series options
sizeKey?: string;
// labelKey as specified on series options
labelKey?: string;
// colorKey as specified on series options
colorKey?: string;
// angleKey as specified on series options
angleKey?: string;
// calloutLabelKey as specified on series options
calloutLabelKey?: string;
// sectorLabelKey as specified on series options
sectorLabelKey?: string;
// radiusKey as specified on series options
radiusKey?: string;
event: Event;
}
interface AgChartClickEvent {
type: T;
event: Event;
}
destroy
Function
Destroy the chart instance and any allocated resources to support its rendering.
