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.
The following sections assume a level of familiarity with common Charts concepts. If you're new to Charts in general, we recommend starting with our Introductory Tutorial instead.
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:
template: `<ag-financial-charts:options="options"/>`,
components: {
'ag-financial-charts': AgFinancialCharts,
},
data() {
return {
options: {
data: getData(),
},
};
}
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:
template: `<ag-gauge :options="options"/>`,
components: {
'ag-gauge': AgGauge,
},
data() {
return {
options: {
type: 'radial-gauge', // or 'linear-gauge'
value: 80,
scale: {
min: 0,
max: 100,
},
}
};
}