The 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.
Configuring Axes
The horizontal (X) and vertical (Y) lines in cartesian charts are referred to as chart axes, and they serve to illustrate the relationships between data points on the graph.
Polar charts such as the Radar Line Series, use angle and radial axes which have similar options.
Axis Types
Every cartesian chart has four axis positions top, bottom, left, right, which can display either Categorical, Numerical, Time, or Logarithmic data.
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
},
],
Note: All of the axes must be specified in order for these changes to take effect.
Secondary Axes
Charts can have more than one axes, allowing for series with different domains to be displayed on the same chart.
Use the keys property to link the series to the axis:
axes: [
// x-axis
{
type: 'category',
position: 'bottom',
},
// primary y-axis
{
type: 'number',
position: 'left',
keys: ['male', 'female'],
},
// secondary y-axis
{
type: 'number',
position: 'right',
keys: ['exportedTonnes'],
},
],
Axis Intervals
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
Axis labels can be formatted, 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
formatter: function (params) {
return params.value * 100 + '%';
},
},
},
];
Enhancing Data
Charts can be enhanced with data elements, such as Legends, Cross Lines, and conditional Stylers to provide additional information to users.
Legend
Legends are enabled by default on charts with more than one series.
Use the legend property to configure the legend position and size:
legend: {
enabled: true, // defaults to true for charts with multiple series
position: 'bottom', // 'top', 'right', 'left',
maxWidth: 200,
maxHeight: 300,
}
Cross Lines
Cross Lines are lines or shaded areas in a chart that denote additional information or thresholds.
Use the crossLines property in the axis options to add a Line or Range at a specific data value on an axis:
axes: [
{
crossLines: [
{
type: 'line',
value: 11,
},
{
type: "range",
range: ["Jun", "Sep"],
},
],
},
],
Customizing Series & Markers
Markers can be customised to change their shape, size, and style.
Use the series.marker property to customise markers:
series: [
// ...
marker: {
shape: 'square', // defaults to 'circle'
size: 20,
fill: 'red',
stroke: 'maroon',
},
]
Conditional Styling
Item Stylers allow customisation of the visual appearance of Series & Markers based on certain conditions.
Use the itemStyler callback function to customise the appearance of a specific Series or Marker:
series: [
{
marker: {
itemStyler: ({ datum, xKey, fill, highlighted }) => {
return {
fill: datum[xKey] === 'Jul' ? (highlighted ? 'lime' : 'red') : fill,
};
},
},
},
];
Customizing Charts
Charts can be customised with Themes, Layouts, and Backgrounds.
Layout
The chart will auto-size by default, taking the size of the container element and auto-sizing the chart dynamically. It will default 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,
}
Background
Use background.fill to set the Background of the chart to any CSS Color:
background: {
fill: 'transparent', // or RGB, HEX, HSL, HWB, or named color
},
Themes
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 with the Theming API.
Use params to set styles across the whole chart, overrides to merge over the defaults within the base theme, and palette to define the colour palette used for the datapoints:
const customTheme: AgChartTheme = {
palette: {
fills: ['#5C2983', '#0076C5', '#21B372', '#FDDE02', '#F76700', '#D30018'],
strokes: ['#881008'],
},
params: {
fontFamily: 'Georgia, serif',
fontSize: 16,
},
overrides: {
common: {
title: {
fontSize: 24,
},
},
bar: {
series: {
label: {
enabled: true,
color: 'white',
},
},
},
}
};
Interactivity
Charts can be made interactive by enabling Tooltips, Highlighting, and responding to Events.
In the above example you can hover a marker to see the highlight and tooltip customisation, and click the chart or legend to see the event handling.
Customizing Tooltips
Tooltips are enabled by default. Their content is based on the data values and keys of the series.
Use the tooltip.renderer callback function to customise the content of the tooltip.
tooltip: {
renderer: function ({ datum, xKey, yKey }) {
return {
heading: 'Clothing Production',
title: yName.toUpperCase(),
data: [
{
label: datum[xKey],
value: datum[yKey].toFixed(1),
},
],
};
},
},
You can also return HTML to create a Custom Tooltip:
{
renderer: function (params) {
return (
'<div class="custom-tooltip">' +
params.datum[params.xKey]
'</div>'
);
},
},
Highlighting Hovered Data
Items and Series can be highlighted when hovered over. Item highlighting is enabled by default.
Use highlightStyles to customise highlighted items and series:
theme: {
overrides: {
bar: {
series: {
highlightStyle: {
// Attributes that apply to individual items within a single series.
item: {
fill: 'red',
stroke: 'maroon',
strokeWidth: 4,
},
// Attributes that apply to the entire series containing the highlighted item.
series: {
dimOpacity: 0.2,
strokeWidth: 2
}
}
},
},
},
},
Handling Events
Callbacks are provided for Series, Legend and Chart events. These include clicks, double-clicks and zoom events.
Use listeners to respond to Events on the chart:
{
// Charts Events
listeners: {
click: (_event) => {
alert('click');
},
doubleClick: (_event) => {
alert('double click');
},
seriesNodeClick: ({ datum, xKey, yKey, seriesId }) => {
alert('node clicked')
},
seriesVisibilityChange: ({ seriesId, visible }: AgSeriesVisibilityChange) => {
alert('series visibility changed')
},
},
// Series Events
series: [
{
listeners: {
nodeClick: (event) => {
console.log('node clicked')
},
},
},
],
// Legend Events
legend: {
listeners: {
legendItemClick: ({ seriesId, itemId, enabled }: AgChartLegendClickEvent) => {
console.log('item clicked')
},
},
}
}
Saving and Restoring State
The dynamic State of the chart can be saved and restored.
Use the getState() and saveState() APIs to retrieve and save 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:
initialState: {
zoom: {
rangeX: {
start: {
__type: 'date',
value: new Date('2021-01-01').getTime(),
},
},
},
...
}
Enterprise Features (e)
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, or request 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 use Zoom on the chart or Navigator, and see the animation on initial load.
Zoom (e)
To Enable Zooming, set the zoom property to true:
zoom: {
enabled: true,
}
Zoom can also be further customised to enable/disable specific zoom methods and control the anchor point, scrolling step, etc:
zoom: {
anchorPointX: 'pointer',
anchorPointY: 'pointer',
scrollingStep: 0.4,
axes: 'xy',
panKey: 'shift',
enableAxisDragging: false,
enablePanning: false,
enableScrolling: false,
enableSelecting: true,
minVisibleItems: 10,
autoScaling: {
enabled: true,
}
}
Navigator (e)
Zoom can also be controlled with a Navigator. To enable the Navigator, set the navigator property to true:
navigator: {
enabled: true,
}
A Mini Chart can also be displayed within the Navigator:
navigator: {
miniChart: {
enabled: true,
},
}
Animations (e)
Animations are enabled by default. Use the animation property to control the duration of animations:
animation: {
duration: 500, // ms
}
Specialized Charts (e)
Financial Charts (e)
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)
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)
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,
},
}
};
}