AG Grid
Best JavaScript Grid in the World
AG Charts
Best JavaScript Charts in the World
AG Studio
Best JavaScript Dashboard in the World
Bryntum Gantt
Speed-tuned Gantt chart for project planning
Bryntum Scheduler
Resource scheduling timeline component
PROPRO
Bryntum Scheduler Pro
Scheduler with auto-scheduling and constraints
Bryntum Calendar
Flexible JavaScript event calendar
Bryntum Task Board
Kanban-style task board component
Search⌘ KCtrl K

JavaScript ChartsEvents

Version 14.2.0

This section explains how to listen and respond to various chart and series events. Most are either clicks or state changes, and listeners live in a listeners option, either on the chart or on individual elements.

Click Events Copy Link

Each clickable part of the chart has its own click event, these are detailed below. Listen on the chart for every occurrence, or on an individual element for just that one.

Every click event has a double-click form which carries the same payload. A double-click fires the single-click event on both clicks, then the double-click event on the second.

Some clicks can also be stopped from applying their built-in behaviour - see Prevent Default.

click and doubleClick Copy Link

These are fired on click or double-click on any empty part of the chart.

These events contain:

  • coordinates - for cartesian series types, the coordinates of the click point as plotted against each axis.
  • These are keyed by axis, with each axis providing direction, the value at the clicked position and its index within the axis domain.
  • The context object, if set.
 
{
    listeners: {
        click: (event) => {
            console.log('[click]', event);
        },
        doubleClick: (event) => {
            console.log('[double click]', event);
        },
    },
}

In this example:

  • When a blank area on a chart is clicked, a message is shown in the console along with the event details.
  • When a blank area on a chart is double-clicked, a different message is shown along with the event details. The single-click event is also fired on both clicks.

seriesNodeClick and seriesNodeDoubleClick Copy Link

These are fired on click or double-click of a series node such as a bar or marker and are defined on the series or chart options.

The parameters of these events differ depending on the series type, but always include:

  • The seriesId the node belongs to and the itemId of the clicked node.
  • The data object being visualised, usually datum.
  • The specific keys in that datum that were used to fetch the values represented by the clicked node.
  • allMatchedParams - every other node matched at the click point. See allMatchedParams.
  • coordinates - the coordinates of the click point, in the same form as the chart click events.
  • The context object, if set.
 
{
    series: [
        {
            type: 'line',
            listeners: {
                seriesNodeClick: (event) => console.log('[line click]', event),
                seriesNodeDoubleClick: (event) => console.log('[line double click]', event),
            },
            // ...
        },
        {
            type: 'bar',
            listeners: {
                seriesNodeClick: (event) => console.log('[bar click]', event),
                seriesNodeDoubleClick: (event) => console.log('[bar double click]', event),
            },
            // ...
        },
    ],
    listeners: {
        seriesNodeClick: (event) => console.log('[chart click]', event),
        seriesNodeDoubleClick: (event) => console.log('[chart double click]', event),
    },
}

In this example:

  • Whenever any series node (bar or marker) is clicked or double-clicked, the Chart listener prints a message to the console with the event details.
  • Whenever a bar is clicked or double-clicked, the Bar Series listener prints a message to the console with the event details.
  • Whenever a marker is clicked or double-clicked, the Line Series listener prints a message to the console with the event details.

Interaction Ranges Copy Link

By default, the seriesNodeClick event is only triggered when the user clicks exactly on a node.

Use the nodeClickRange option to instead define a range at which the event is triggered.

 
{
    series: [
        {
            type: 'line',
            nodeClickRange: 'exact',
            listeners: {
                seriesNodeClick: ({ datum }) => console.log(`petrol - ${datum.petrol}`),
            },
            // ...
        },
    ],
}

In this example:

  • 'exact' (default) will trigger the event if the user clicks exactly on a node.
  • 'nearest' will trigger the event for whichever node is nearest to the click.
  • Given a number it will trigger the event when the click is made within that many pixels of a node.
  • Area Series also supports 'area' as a value for nodeClickRange. This triggers the event when the click is made anywhere within the filled area of the series.

axisClick and axisDoubleClick (e) Copy Link

These are fired on click or double-click of an axis area or any of its elements and are defined on the axes or chart options.

These events contain:

  • The axisId of the axis, as specified on the axis or automatically generated.
  • The direction of the axis.
  • The value on the axis at the clicked point, matching the axis type, along with its index in the axis domain.
  • The boundSeries listing all series that are using the axis.
  • The context object, if set.
 
{
    axes: {
        x: {
            listeners: {
                click: (event) => console.log('[x axis click]', event),
                doubleClick: (event) => console.log('[x axis double click]', event),
            },
            // ...
        },
        yProfit: {
            listeners: {
                click: (event) => console.log('[profit axis click]', event),
                doubleClick: (event) => console.log('[profit axis double click]', event),
            },
            // ...
        },
    },
    listeners: {
        axisClick: (event) => console.log('[chart axis click]', event),
        axisDoubleClick: (event) => console.log('[chart axis double click]', event),
    },
}

In this example:

  • Whenever the x-axis is clicked or double-clicked, the x-axis listener prints a message to the console.
  • Whenever the left hand "Profit" axis is clicked or double-clicked, the yProfit Axis listener prints a message to the console.
  • Whenever any x-axis or y-axis is clicked or double-clicked, the Chart listener prints a message to the console.

crossLineClick and crossLineDoubleClick Copy Link

These are fired on click or double-click of a Cross Line, including its label. This can be defined on the Cross Line itself, the axis or the chart.

These events contain:

  • The crossLineId, as specified on the Cross Line or automatically generated.
  • The axisId and direction of the axis the Cross Line belongs to.
  • The crossLineType, either 'line' or 'range'.
  • The value of a line Cross Line, or the range of a range Cross Line.
  • allMatchedParams - every element under the click point, including other Cross Lines or series node. See allMatchedParams.
  • The context object, if set.
 
{
    axes: {
        x: {
            crossLines: [
                {
                    id: 'winter-lockdown',
                    listeners: {
                        click: (event) => console.log('[lockdown click]', event),
                        doubleClick: (event) => console.log('[lockdown double click]', event),
                    },
                    // ...
                },
            ],
            listeners: {
                crossLineClick: (event) => console.log('[x axis cross line click]', event),
                crossLineDoubleClick: (event) => console.log('[x axis cross line double click]', event),
            },
            // ...
        },
    },
    listeners: {
        crossLineClick: (event) => console.log('[chart cross line click]', event),
        crossLineDoubleClick: (event) => console.log('[chart cross line double click]', event),
    },
}

In this example:

  • Whenever a lockdown range or the ICU capacity line is clicked or double-clicked, that Cross Line's own listener prints a message to the console.
  • Whenever a Cross Line on the x-axis is clicked or double-clicked, the x-axis listener prints a message to the console.
  • Whenever any Cross Line is clicked or double-clicked, the Chart listener prints a message to the console.
  • Clicking where a variant line crosses a lockdown range, lists both Cross Lines in allMatchedParams.

legendItemClick and legendItemDoubleClick Copy Link

These are fired on click or double-click of a legend item.

These events contain:

  • The seriesId of the series associated with the legend item.
  • The itemId, usually the yKey value for cartesian series.
  • The current visible state of the series or item.
  • The preventDefault() method to stop any built-in series visibility toggle that would otherwise occur.
  • The context object, if set.

Although clicking a legend item usually toggles the series visibility, this change is not included in the legend event. Use the chart seriesVisibilityChange event to listen for this.

 
{
    legend: {
        listeners: {
            legendItemClick: (event) => {
                console.log('[click]', event);
            },
            legendItemDoubleClick: (event) => {
                console.log('[double click]', event);
            },
        },
    },
}

In this example:

  • When a legend item is clicked, a message is logged to the console with the legendItemClick event contents.
  • When a legend item is double clicked, a message is logged to the console with the legendItemDoubleClick event contents.

captionClick and captionDoubleClick Copy Link

These are fired on click or double-click of the chart's title, subtitle or footnote. These are defined on the caption itself or on the chart.

These events contain:

  • The captionType, either 'title', 'subtitle' or 'footnote'.
  • The text of the clicked caption.
  • The context object, if set.
 
{
    title: {
        text: 'Number of Cars Sold',
        listeners: {
            click: (event) => console.log('[title click]', event),
            doubleClick: (event) => console.log('[title double click]', event),
        },
    },
    // ...
    listeners: {
        captionClick: (event) => console.log('[chart caption click]', event),
        captionDoubleClick: (event) => console.log('[chart caption double click]', event),
    },
}

In this example:

  • Whenever the title, subtitle or footnote is clicked or double-clicked, the Chart listener prints a message to the console with the event details.
  • The title has its own listeners, so clicking or double-clicking on it prints a second message.

allMatchedParams Copy Link

Most click events include an allMatchedParams array listing every element found at the click point, not only the one that won the event. This is useful for scenarios where multiple elements overlap, such as a Cross Line and a series node.

Each entry is identified by its own type, matching the specific event it would have delivered for that interaction and includes the same properties as it would have carried. The winning event is also included in the array.

See the Cross Line Click Event example above: clicking where a variant line crosses a lockdown range lists both Cross Lines in allMatchedParams.

State Change Events Copy Link

These are raised when the chart state changes, by either user interaction or an API call and are always defined on the chart options.

seriesVisibilityChange Copy Link

This is fired when the visibility of a series or data item is toggled. This is usually triggered by user interaction with a legend item.

This event contains:

  • The seriesId of the series.
  • The itemId, legendItemName or other identifiers of the changed item.
  • visible - the new visibility state of the series or item.
  • The context object, if set.
 
{
    listeners: {
        seriesVisibilityChange: (event) => {
            console.log('[series visibility change]', event);
        },
    },
}

In this example:

  • When a legend item is clicked, its series or item visibility toggles and this event fires with the details shown in the console.

activeChange Copy Link

This event is fired when the active state is changed. This occurs when a user interaction (mouse, touch, keyboard) on a series node or legend causes a highlight or tooltip change.

This event contains:

  • activeItem - the item that is now active, or undefined if no item is active.
  • The activeItem contains:
    • type - the type of the active item, either 'series-node' or 'legend'.
    • seriesId and itemId identifying the active item.
  • datum - the data from the chart data array for the active item.
  • source - the source of the event, either 'user-interaction' or 'state-change'.
  • The preventDefault() method to stop the highlight/tooltip change that would otherwise occur.
  • The context object, if set.
 
{
    listeners: {
        activeChange: (event) => {
            console.log('[active change]', event);
        },
    },
}

In this example:

  • Whenever a user interaction (mouse, touch, keyboard) on the series-area or legend changes the highlight state, a message is shown in the console.

zoom Copy Link

This is fired when the zoom level or position changes. This is triggered when zooming in or out of the chart, panning, or using the Navigator, Scrollbar or Range Buttons.

This event contains:

  • A ratioX and ratioY with start and end properties with values between 0 and 1. These represent a proportion of the width or height of the chart.
  • A rangeX and rangeY which contain values that match the axis type, e.g. a date for an Ordinal Time Axis.
  • source - the source of the event: 'user-interaction', 'state-change', 'chart-update', 'data-update' or 'sync'.
  • The context object, if set.
 
{
    listeners: {
        zoom: (event) => {
            console.log(event);
        },
    },
}

In this example:

  • When the zoom level is changed or the chart is panned, the event is output to the console.

annotations Copy Link

This is fired when the annotations are changed, added or removed in either cartesian charts or with the financial charts toolbar.

This event contains:

  • The array of all the annotations with their current state.
  • The context object, if set.
 
{
    listeners: {
        annotations: (event) => {
            console.log(event);
        },
    },
}

In this example:

  • When an annotation is changed, added or removed, the event is output to the console.

selectionChange Copy Link

This is fired when the Data Selection is updated by either user interaction or an API call. See Selection Change Event for full details.

collapsedChange Copy Link

This is fired when an item in an Org Chart is expanded or collapsed, by either user interaction or an API call.

 
{
    listeners: {
        collapsedChange: (event) => {
            console.log(
                `source: ${event.source},`,
                'just collapsed:',
                event.collapsed.map(({ itemId }) => itemId),
                'just expanded:',
                event.expanded.map(({ itemId }) => itemId)
            );
        },
    },
}

This event contains:

  • collapsed - array of the items newly collapsed by this change, each with itemId and datum:
    • itemId - the unique identifier of the datum.
    • datum - the data from the chart data array for the collapsed item.
  • expanded - array of the items newly expanded by this change, each with itemId and datum:
    • itemId - the unique identifier of the datum.
    • datum - the data from the chart data array for the expanded item.
  • source - the source of the event, either 'user-interaction' or 'api-call'.
  • The context object, if set.

In this example:

  • Whenever a node is collapsed or expanded, a message is shown in the console.

collapsed and expanded contain only the items changed by this event, not the full set of collapsed or expanded items. Use chart.getState() to get the current state of all items.

Validation Issues Copy Link

Option misconfiguration and caught runtime errors are reported through the validations.issueRaised event.

See Issue Raised Events.

Prevent Default Copy Link

Some events include a preventDefault() method to stop the built-in behaviour that would otherwise follow the interaction.

Call event.preventDefault() from within the listener, and check event.defaultPrevented to see whether an earlier listener already called it.

The events that can be prevented are:

  • legendItemClick and legendItemDoubleClick - stops the series visibility toggle that a legend click would otherwise trigger.
  • seriesNodeClick, seriesNodeDoubleClick - stops any tooltip pagination or selection that a node click would otherwise trigger.
  • activeChange - stops the highlight/tooltip change itself from being applied.
  • selectionChange - stops the Data Selection update.
  • collapsedChange - stops the Org Chart node from expanding or collapsing.
 
{
    legend: {
        listeners: {
            legendItemClick: (event) => {
                counter = (counter + 1) % 2;
                if (counter !== 1) {
                    event.preventDefault();
                }
            },
        },
    },
}

In this example:

  • When a legend item is clicked, the visibility change is prevented and a counter decreases instead, by calling preventDefault on the legendItemClick event.
  • When the counter hits zero, the toggle is allowed to occur and the seriesVisibilityChange event fires.

Item Identifiers Copy Link

Many events expose an itemId to identify the item within its series. How it is derived depends on the item type:

  • Series nodes use a node identifier.
    • Automatically generated from the data, and may change when the data updates.
    • Set dataIdKey to use a datum field as a stable identifier across data updates (see Identifying Items by Key).
    • Series whose nodes don't map directly to a datum - such as Histogram bins and Sankey or Chord nodes - expose a getItemId callback instead.
    • Waterfall total and subtotal bars use their totals.itemId if set, otherwise their totals.axisLabel.
  • Legend items use the legend item's identifier. Typically the yKey value for most series, or the legend item's position for series with one legend item per datum, such as pie and donut.

API Reference Copy Link

All series event options have similar interface contracts. See the series-specific documentation for variations.

Properties available on the AgSeriesListeners interface.

seriesNodeClick Listener
The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is clicked.
seriesNodeDoubleClick Listener
The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is double-clicked.

Properties available on the AgBaseSeriesOptions interface.

nodeClickRange InteractionRange
Range from a node that a click triggers the listener.

Properties available on the AgChartLegendListeners interface.

legendItemClick Function
The listener to call when a legend item is clicked.
legendItemDoubleClick Function
The listener to call when a legend item is double-clicked.

Axis listeners. Cross Line listeners are Cartesian charts only.

click Listener
The listener to call when the axis is clicked.
doubleClick Listener
The listener to call when the axis is double-clicked.

Cross Line listeners can also be set on the axis that owns the Cross Line.

Cross Line listeners. Cartesian charts only.

click Listener
The listener to call when the Cross Line is clicked.
doubleClick Listener
The listener to call when the Cross Line is double-clicked.

Axis listeners. Cross Line listeners are Cartesian charts only.

crossLineClick Listener
The listener to call when a Cross Line on this axis is clicked.
crossLineDoubleClick Listener
The listener to call when a Cross Line on this axis is double-clicked.

Caption listeners can be set on the chart's title, subtitle and footnote.

Properties available on the AgCaptionListeners interface.

click Listener
The listener to call when the caption is clicked.
doubleClick Listener
The listener to call when the caption is double-clicked.

Properties available on the AgBaseChartListeners interface.

captionClick Listener
The listener to call when any caption (title, subtitle or footnote) in the chart is clicked.
captionDoubleClick Listener
The listener to call when any caption (title, subtitle or footnote) in the chart is double-clicked.

Properties available on the AgBaseChartListeners interface.

seriesNodeClick Listener
The listener to call when a node (marker, column, bar, tile or a pie sector) in any series is clicked. Useful for a chart containing multiple series.
seriesNodeDoubleClick Listener
The listener to call when a node (marker, column, bar, tile or a pie sector) in any series is double-clicked. Useful for a chart containing multiple series.
axisClick Listener
The listener to call when any axis in the chart is clicked. Useful for a chart containing multiple axes.
axisDoubleClick Listener
The listener to call when any axis in the chart is double-clicked. Useful for a chart containing multiple axes.
captionClick Listener
The listener to call when any caption (title, subtitle or footnote) in the chart is clicked.
captionDoubleClick Listener
The listener to call when any caption (title, subtitle or footnote) in the chart is double-clicked.
seriesVisibilityChange Listener
The listener to call when a series visibility is changed.
activeChange Listener
The listener to call when the active state (highlight/tooltip) is changed.
selectionChange Listener
The listener to call when data selection is changed
collapsedChange Listener
The listener to call when collapsed items are changed.
click Listener
The listener to call when the chart is clicked.
doubleClick Listener
The listener to call when the chart is double-clicked.
crossLineClick Listener
The listener to call when a Cross Line on any axis is clicked.
crossLineDoubleClick Listener
The listener to call when a Cross Line on any axis is double-clicked.
annotations Listener
The listener to call when the annotations are changed.
zoom Listener
The listener to call when the zoom is changed.