Methods
If you want to change the chart at runtime after it has rendered, you may call the following methods of ApexCharts on the chart instance.
render ()
The render() method is responsible for drawing the chart on the page. It is the primary method that has to be called after configuring the options.
Returns
Promise
Once the chart is drawn on the page, a promise is returned
Example
var chart = new ApexCharts(el, options);
chart.render()
exec (chartID, methodName, options)
If you want to call chart methods without referencing the instance of the chart, you can call the exec() method directly.
The exec() method takes chartID as the first parameter and finds the chart instance based on that ID to execute method on that chart instance.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| chartID | String | undefined | The chartID used to identify the chart instance to execute the method on. |
| methodName | String | '' | Any function which can directly be called on chart instance can be named in method parameter. |
| options | Object || Array | The parameters which are accepted in the original method will be passed here in the same order. Below you will find an example of how variable number of parameters are passed to different functions. |
Returns
Promise
After the chart is rendered, a promise is returned
Example
var chart = new ApexCharts(el, {
chart: {
id: 'mychart',
type: 'area'
},
series: [{
data: [2, 33, 14, 8]
}]
});
ApexCharts.exec('mychart', 'updateOptions', {
xaxis: {
labels: {
show: false
}
}
}, false, true);
ApexCharts.exec('mychart', 'updateSeries', [{
data: [32, 44, 31, 41, 22]
}], true);
updateOptions (newOptions, redrawPaths, animate, updateSyncedCharts)
This method allows you to update the configuration object by passing the options as the first parameter. The new config object is merged with the existing config object preserving the existing configuration.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| newOptions | Object | null | The configuration object to merge on the existing one |
| redrawPaths | Boolean | false | When the chart is re-rendered, should it draw from the existing paths or completely redraw the chart paths from the beginning. By default, the chart is re-rendered from the existing paths |
| animate | Boolean | true | Should the chart animate on re-rendering |
| updateSyncedCharts | Boolean | true | All the charts in a group should also update when one chart in a group is updated. |
Returns
Promise
After the chart is rendered again, a promise is returned
Example
var chart = new ApexCharts(el, options);
chart.updateOptions({
xaxis: {
labels: {
show: false
}
},
yaxis: {
min: 20,
max: 100
}
})
updateSeries (newSeries, animate)
Allows you to update the series array overriding the existing one. If you want to append series to existing series, use the appendSeries() method
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| newSeries | Array | [ ] | The series array to override the existing one |
| animate | Boolean | true | Should the chart animate on re-rendering |
Returns
Promise
After the chart is rendered again, a promise is returned
Example
var chart = new ApexCharts(el, options);
chart.updateSeries([{
data: [32, 44, 31, 41, 22]
}])
// example of series in another format
chart.updateSeries([{
data: [{
x: "02-02-2002",
y: 44
}, {
x: "12-02-2002",
y: 51
}]
}])
In cases where you want to update both the series and options together, it is recommented to just call the updateOptions method as shown below.
chart.updateOptions({
series: [{
data: [{
x: "02-02-2002",
y: 44
}, {
x: "12-02-2002",
y: 51
}]
}],
xaxis: {
position: 'top'
}
})
appendSeries (newSeries, animate)
This method allows you to append a new series to the existing one.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| newSeries | Object | The series object to append the existing one | |
| animate | Boolean | true | Should the chart animate on re-rendering |
Returns
Promise
After the chart is rendered again, a promise is returned
Example
var chart = new ApexCharts(el, options);
chart.appendSeries({
name: 'newSeries'
data: [32, 44, 31, 41, 22]
})
toggleSeries (seriesName)
This method allows you to toggle the visibility of series programmatically. Useful when you have a custom legend.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| seriesName | String | undefined | The series name which you want to toggle visibility for. |
Returns
Boolean
The return value indicates whether the series was hidden or shown
Example
var chart = new ApexCharts(el, {
series: [{
name: 'Football'
data: [33, 23, 76, 33]
}, {
name: 'Cricket'
data: [23, 33, 16, 23]
}]
});
chart.toggleSeries('Football')
toggleSeries() Example with Custom Legend
showSeries (seriesName)
This method allows you to show the hidden series. If the series is already visible, this doesn't affect it.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| seriesName | String | undefined | The series name which you want to show. |
Example
var chart = new ApexCharts(el, {
series: [{
name: 'Football'
data: [33, 23, 76, 33]
}, {
name: 'Cricket'
data: [23, 33, 16, 23]
}]
});
chart.showSeries('Football')
hideSeries (seriesName)
This method allows you to hide the visible series. If the series is already hidden, this method doesn't affect it.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| seriesName | String | undefined | The series name which you want to hide. |
Example
var chart = new ApexCharts(el, {
series: [{
name: 'Soccer'
data: [33, 23, 76, 33]
}, {
name: 'Cricket'
data: [23, 33, 16, 23]
}]
});
chart.hideSeries('Cricket')
highlightSeries (seriesName)
This method allows you to highlight a series programmatically. The rest of the series becomes dim in order to give more visual emphasis to the highlighted series.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| seriesName | String | undefined | The series name which you want to highlight. |
Returns
null
Example
var chart = new ApexCharts(el, {
series: [{
name: 'Football'
data: [33, 23, 76, 33]
}, {
name: 'Cricket'
data: [23, 33, 16, 23]
}]
});
chart.highlightSeries('Football')
zoomX (start, end)
Manually zoom into the chart with the start and end X values.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| start X | Number | undefined | The starting x-axis value. Accepts timestamp or a number |
| end X | Number | undefined | The ending x-axis value. Accepts timestamp or a number |
Example
var chart = new ApexCharts(el, {
series: [{
data: [33, 23, 76, 33]
}]
});
chart.zoomX(new Date('2011-02-01').getTime(), new Date('2011-02-10').getTime())
resetSeries (shouldUpdateChart, shouldResetZoom)
Resets all toggled series and bring back the chart to its original state.
Optional Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| shouldUpdateChart | Boolean | true | After resetting the series, the chart data should update and return to it's original series. |
| shouldResetZoom | Boolean | true | If the user has zoomed in when this method is called, the zoom level should also reset. |
Example
var chart = new ApexCharts(el, {
series: [{
name: 'Football'
data: [33, 23, 76, 33]
}, {
name: 'Cricket'
data: [23, 33, 16, 23]
}]
});
chart.toggleSeries('Football')
chart.resetSeries()
appendData (newData)
This method allows you to append new data to the series array. If you have existing multiple series, provide the new array in the same indexed order.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| newData | Array | [ ] | The data array to append the existing series datasets |
Returns
Promise
After the chart is rendered again, a promise is returned
Example
var chart = new ApexCharts(el, options);
chart.appendData([{
data: [32, 44, 31, 41, 22]
}, {
data: [12, 11, 32, 44, 5]
}])
toggleDataPointSelection (seriesIndex, dataPointIndex)
This method allows you to select/deselect a data-point of a particular series.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| seriesIndex | Number | undefined | Index of the series array. If you are rendering a pie/donut/radialBar chart, this acts as dataPointIndex and is the only thing you have to provide as pie/donut/radialBar don't support multi-series chart. |
| dataPointIndex | Number | undefined | Index of the data-point in the series selected in previous argument. Not required in pie/donut/radialBar |
Returns
The DOM element which is toggled is returned. If not found, returns null
Example
var chart = new ApexCharts(el, {
chart: {
type: 'bar'
},
series: [{
data: [32, 44, 65, 12, 63]
}, {
data: [42, 12, 43, 53, 44]
}]
});
chart.toggleDataPointSelection(1, 3);
// This will toggle the 4th element of the 2nd series i.e. 53 and highlight the DOM element with a different shade.
Q: How do you know which data points are already selected?
A: You can use chart.w.globals.selectedDataPoints array which contains necessary information. In the example above, chart.w.globals.selectedDataPoints will contain [undefined, [3]].
This also trigger the chart.dataPointSelection event
addXaxisAnnotation (options, pushToMemory)
The addXaxisAnnotation() method can be used to draw annotations after chart is rendered.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| options | Object | This function accepts the same parameters as it accepts in the annotations x-axis config. | |
| pushToMemory | Boolean | true | When enabled, it preserves the annotations in subsequent chart updates. If you don't want it to be saved for the next updates, turn off this option |
Returns
ApexCharts context
Example
var chart = new ApexCharts(el, options);
chart.addXaxisAnnotation({
x: 40,
label: {
text: 'Lorem Ipsum'
},
})
addYaxisAnnotation (options, pushToMemory)
The addYaxisAnnotation() method can be used to draw annotations after chart is rendered.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| options | Object | This function accepts the same parameters as it accepts in the annotations y-axis config. | |
| pushToMemory | Boolean | true | When enabled, it preserves the annotations in subsequent chart updates. If you don't want it to be saved for the next updates, turn off this option |
Returns
ApexCharts context
Example
var chart = new ApexCharts(el, options);
chart.addYaxisAnnotation({
y: 40,
yAxisIndex: 0,
label: {
text: 'Lorem Ipsum'
},
})
addPointAnnotation (options, pushToMemory)
The addPointAnnotation() method can be used to draw annotations after chart is rendered.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| options | Object | This function accepts the same parameters as it accepts in the point annotations config. | |
| pushToMemory | Boolean | true | When enabled, it preserves the annotations in subsequent chart updates. If you don't want it to be saved for the next updates, turn off this option |
Returns
ApexCharts context
Example
var chart = new ApexCharts(el, options);
chart.addPointAnnotation({
x: new Date('15 Jan 2017').getTime(),
y: 40,
label: {
text: 'Lorem Ipsum'
},
})
removeAnnotation (id)
The removeAnnotation() method can be used to delete any previously added annotations. Only annotations which are added by external methods (addPointAnnotation, addXaxisAnnotation, addYaxisAnnotation) are affected. Annotations defined in the options/config object are not affected.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| id | String | undefined | The unqiue identifier of the annotation which was created using the addPointAnnotation, addXaxisAnnotation or addYaxisAnnotation methods. |
Returns
None
Example
var chart = new ApexCharts(el, options);
chart.addPointAnnotation({
id: 'my-annotation',
x: new Date('15 Jan 2017').getTime(),
y: 40,
label: {
text: 'Lorem Ipsum'
},
})
chart.removeAnnotation('my-annotation')
clearAnnotations ()
The clearAnnotations() method is used to delete all annotation elements which are added dynamically using the three methods stated above.
Parameters
None
Returns
ApexCharts context
Example
var chart = new ApexCharts(el, options);
chart.clearAnnotations()
dataURI ({ scale, width })
The dataURI() method is used to get base64 dataURI. Then this dataURI can be used to generate PDF using jsPDF
Parameters
| Name | Type | Description |
|---|---|---|
| options | Object | The options object accepts scale or width property which allows to adjust the size of the exported graphic. scale/width both accepts a number. |
Returns
Promise
Example
var chart = new ApexCharts(el, options);
var dataURL = chart.dataURI().then(({ imgURI, blob }) => {
const { jsPDF } = window.jspdf
const pdf = new jsPDF();
pdf.addImage(imgURI, 'PNG', 0, 0);
pdf.save("pdf-chart.pdf");
})
clearAnnotations ()
Once you have set the default locale initially by chart.defaultLocale property, you can dynamically change it during runtime using setLocale() method. The method assumes that you have already specified the locales array in chart.locales when initializing the charts.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| localeName | String | undefined | The 2 digit locale code which you provide in the chart.locales option. |
Returns
None
Example
var chart = new ApexCharts(el, options);
chart.setLocale('fr')
destroy ()
Removes the SVG element that belongs to the chart instance also removing all events handlers attached to it.
Example
var chart = new ApexCharts(el, options);
chart.destroy();
drillDown (id)
Opens the drilldown level with the given id, as if the reader had clicked a point that targets it. Requires the Drilldown feature.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| id | String | Number | undefined | The id of a drilldown.series entry to open. |
Returns
A promise that resolves with the chart instance once the transition completes.
Example
chart.drillDown('mobile')
drillUp ()
Navigates back one drilldown level. Requires the Drilldown feature.
Returns
A promise that resolves with the chart instance once the transition completes.
Example
chart.drillUp()
drillToRoot ()
Navigates back to the root (top) drilldown level. Requires the Drilldown feature.
Returns
A promise that resolves with the chart instance once the transition completes.
Example
chart.drillToRoot()
clearDrilldownCache (id)
Clears levels cached by drilldown.onDrillDown. Call it when the underlying data changes, so drilling back down re-fetches instead of serving a stale level. Requires the Drilldown feature.
Optional Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| id | String | Number | undefined | Clear one cached level. Omit to clear all of them. |
Returns
The chart instance.
Example
chart.clearDrilldownCache() // everything
chart.clearDrilldownCache('mobile') // one level
rowSeries ({ maxRows })
Returns the rows behind the marks the chart is currently drawing, as a series.
A histogram bin, a box and a violin each stand for observations the chart is already holding. rowSeries() hands them back, which makes the summary and the observations two views of one dataset rather than two datasets you have to keep in step:
Optional Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| maxRows | Number | undefined | Cap the number of rows returned. Useful when a bin holds more observations than you want to draw as individual marks. |
Returns
An array of row clusters, one per mark, or null when the current chart type has no row source.
Example
chart.updateOptions({
chart: { type: 'unit' },
series: chart.rowSeries()
})
The row sources ship with the statistics behind apexcharts/features/stats; core keeps only the lookup. See tree-shaking.
getPanels ()
Returns the panels of a trellis host, in grid order. Empty for a chart that is not a trellis.
Requires the trellis feature: import 'apexcharts/features/trellis'.
Returns
An array of { key, index, chart, el }. key is the facet key ('North' in a 1-D grid, 'Sales / Q1' in a 2-D one), chart is that panel's own ApexCharts instance, and el is its cell element.
Example
chart.getPanels().forEach(({ key, chart: panel }) => {
panel?.updateOptions({ stroke: { width: 3 } })
})
chart is null before a panel mounts, and for a virtualized panel currently offscreen.
getPanel (key)
One trellis panel's own ApexCharts instance, by facet key. The escape hatch to every per-chart API the trellis host does not re-expose.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| key | String | undefined | The panel's facet key, as it appears in getPanels(). |
Returns
The panel's ApexCharts instance, or null when no panel carries that key and when the panel is not currently mounted under virtualization.
Example
chart.getPanel('North')?.addYaxisAnnotation({ y: 70, borderColor: '#DC2626' })
promotePanel (key)
Expands one trellis panel to the grid's full width, which is what clicking its header does. No-op on a chart that is not a trellis host.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| key | String | undefined | The panel's facet key. |
Returns
A promise that settles when the promotion has rendered.
Example
await chart.promotePanel('checkout')
Set trellis.promote: false to remove the header affordance and drive promotion only from code.
restorePanels ()
Restores the grid from a panel promotion, which is what the "All panels" breadcrumb does.
Returns
A promise that settles when the grid has rendered.
Example
await chart.restorePanels()
ApexCharts.trellis (el, options)
Static method. Creates a trellis host and starts rendering it, for code that would otherwise construct a chart and immediately render it.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| el | HTMLElement | undefined | The element to render the grid into. |
| options | Object | undefined | Chart options, which must carry trellis.by (or trellis.row / trellis.column). |
Returns
The host instance, or null when the trellis feature is not loaded. Calling render() on the returned instance settles with the same in-flight mount rather than starting a second one.
Example
const chart = ApexCharts.trellis(document.querySelector('#grid'), {
chart: { type: 'line' },
series: rows,
trellis: { by: 'region' },
})
ApexCharts.registerUnitLayout (name, fn)
Static method. Registers a named layout provider for plotOptions.unit.layout: 'custom', so an arrangement can be reused across charts instead of being inlined per chart.
A layout is objects in, positions out: it takes (objects, rect) and returns [{ id, x, y, r? }]. It knows nothing about animation, because the engine already tweens position, radius and colour and already keeps a mark's identity across a relayout.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| name | String | undefined | The name referenced by plotOptions.unit.positions. |
| fn | Function | undefined | (objects, rect) => [{ id, x, y, r? }] |
Example
ApexCharts.registerUnitLayout('silhouette', (objects, rect) =>
objects.map((o, i) => ({
id: o.id,
x: rect.x + (i % 20) * 14,
y: rect.y + Math.floor(i / 20) * 14
}))
)
// then, on any chart
plotOptions: { unit: { layout: 'custom', positions: 'silhouette' } }
ApexCharts.unregisterUnitLayout (name)
Static method. Removes a layout registered with registerUnitLayout. Charts referencing it by name fall back to the grouped layout on their next render.
Example
ApexCharts.unregisterUnitLayout('silhouette')
ApexCharts.registerUnitMark (name, def)
Static method. Registers a named unit-chart mark (a pictogram glyph), referenceable via plotOptions.unit.pictogram.mark.
The twin of registerUnitLayout, and the split between them is the one the unit chart is built on: a layout is where the marks go, a mark is what one of them looks like. They compose freely, so positions: 'heart' with shape: 'pictogram' arranges glyphs into a heart and neither registry has to know about the other.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| name | String | undefined | The name referenced by plotOptions.unit.pictogram.mark. |
| def | String | Object | undefined | Raw path data, or { path, viewBox?, fillRule? }. viewBox defaults to [0, 0, 100, 100]. |
Example
ApexCharts.registerUnitMark('cup', {
path: 'M20 30 h50 v30 a25 25 0 0 1 -50 0 z',
viewBox: [0, 0, 100, 100],
fillRule: 'nonzero'
})
// then, on any chart
plotOptions: { unit: { shape: 'pictogram', pictogram: { mark: 'cup' } } }
Marks are fill-only: the chart positions a glyph with a uniform scale fitted to the radius the layout chose, so any stroke width would scale with it.
ApexCharts.unregisterUnitMark (name)
Static method. Removes a mark registered with registerUnitMark. Charts referencing it by name fall back to pictogram.fallback on their next render.
Example
ApexCharts.unregisterUnitMark('cup')
ApexCharts.registerRowSource (name, fn)
Static method. Registers a row source, i.e. how a chart type maps a mark back to the rows it stands for, which is what rowSeries() reads.
The built-in sources for histogram, boxPlot and violin ship behind apexcharts/features/stats. Register your own to make rowSeries() work for a custom series type.
Example
ApexCharts.registerRowSource('myType', (ctx) => [/* row clusters */])
ApexCharts.unregisterRowSource (name)
Static method. Removes a row source registered with registerRowSource.
Example
ApexCharts.unregisterRowSource('myType')