Handle Click Events

On this page

Prerequisites

Click Event Syntax
Payload
event Element
data Element
selectionFilter Element
target Element
Examples
Basic Handling of Click Events
Interactive Filtering for Click Events

Note

Click Events in the Charts Embedding SDK is available in version 2.1.0 and later.

The Charts Embedding JavaScript SDK includes a click event handler that allows you to subscribe to click events. When you click on a particular element on your chart, the click event handler captures details of the element that you clicked. Use this feature to build interactive experiences similar to the following in your application:

Click on an element on a chart and open a pane with more details on the clicked element.
Create a filter for another chart.

Prerequisites

Before you begin, install version 2.1.0 or later of the Charts Embedding JavaScript SDK.

Click Event Syntax

The event handler takes an event type, click, and a callback function that contains information about the click event and the clicked element as a single payload object. The click event handler syntax looks similar to the following:

chart.addEventListener("click", callback);

The event handler also allows you to define the mark roles for which you want to receive event information, thus eliminating the need to check the payload. The click event handler syntax for defining the mark roles to filter by looks similar to the following:

const options = { includes: [{ roles: ['mark', 'axis-label'] }] };
chart.addEventListener("click", callback, options);

The click event handler must be added after the chart has finished rendering, as shown in the following example:

Example

chart.render(document.getElementById("chart")).then(
     () => chart.addEventListener('click',
       (payload) => alert(JSON.stringify(payload)),
       options)
   );

Note

If you specify the options parameter, the click event handler captures events only if the clicked mark's role matches one of the values specified in the parameter. If you omit this parameter, the click event handler captures all click events on the chart.

Payload

You can use the click event payload to construct a custom filter that you can apply on other charts in your application. The syntax of the payload object for the callback function looks similar to the following:

chart.addEventListener("click", (payload) => {
    // handle events
}

The following example payload object shows the elements inside the payload:

Example

{
  "chartId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "chartTitle": "This is my chart's title",
  "chartDescription": "This is my chart's description",
  "event": { // information about the mouse event. For example:
    "type": "click", // event type
    "altKey": false, // modifier keys
    "ctrlKey": false,
    "shiftKey": false,
    "metaKey": false,
    "offsetX": 152, // element coordinates
    "offsetY": 176,
    "clientX": 172, // coordinates from application viewpoint
    "clientY": 241,
    "pageX": 172, // coordinates relative to the page
    "pageY": 241,
    "screenX": 172, // coordinates relative to screen
    "screenY": 312
  },
  "data": { // information about the clicked chart element. For example:
    "y": {
      "label": "unwind array 'genres'",
      "value": "Adventure"
    },
    "x": {
      "label": "count ( _id )",
      "value": 659
    },
    "color": {
      "label": "year",
      "value": "2000 - 2010",
      "lowerBound": 2000,
      "upperBound": 2010
    }
  },
  selectionFilter: {
    // category data expressed as MQL filter query that
    // interactive filters would output to filter other charts.
    // For example:
    genres: 'Adventure',
    year: {
      $gte: 2000,
      $lt: 2010,
    },
  },
  "target": { // information about the clicked target. For example:
    "type": "rect", // type of mark, such as rect, line, etc.
    "role": "mark", // role of mark, such as mark, legend, etc.
    "fill": "#8CB6F2" // fill color of the mark
  },
  "apiVersion": 1 // API version of event payload
}

To learn more about the elements inside the payload object, see:

event Element
data Element
selectionFilter Element
target Element

`event` Element

The event element of the payload contains information about the mouse event including:

The type of mouse event, which must be click
The modifier keys used to trigger a click event such as altKey, ctrlKey, shiftKey, metaKey
The X and Y coordinates:
- Relative to the canvas element of the chart
- From the application viewpoint
- Relative to the page
- Relative to the screen

`data` Element

The data element of the payload contains information about the clicked chart element. For each encoded data field (x, y, series, intensity, color, shape, size, label, arc, value, target, number, display, text, location), the data element contains:

The channel label
The value of the clicked element
The lower bound for numeric or date binning only

For tables, the Charts Embedding JavaScript SDK click event handler captures click events for fields that represent the channel data for the clicked element:

groups field, which contains all Groups channels including label and value
cell field, which contains the column header label and value of the clicked cell

For geospatial charts, the Charts Embedding JavaScript SDK click event handler captures click events for the following elements:

For choropleth charts, the click event handler captures the fields that represent the channel data for the clicked element:
- lat field, which contains latitude
- lng field, which contains longitude
- location field, which contains the field label and value of the clicked geospatial area
For geospatial scatter charts, the click event handler captures the fields that represent the channel data for the clicked element:
- geopoint field, which contains the field name, value in GeoJSON format, and the coordinates of the clicked point

`selectionFilter` Element

The selectionFilter element of the payload must contain a valid MQL filter document, which represents the filter that corresponds to the clicked mark's category channels or x value channel on a continuous chart. You can modify or implement your own selectionFilter.

The filter object represents a single clicked item:

A string or unbinned number or date, which becomes an equality match query ({field: value}) or a query using $eq, $ne, $in, or $nin operators.
A binned number or date, which becomes a query using gt, $gte, $lt, or lte operators. Periodic dates are ignored.

Example

{ field: 'value' }
{ field1: 'value1', field2: 'value2' }
{ field: { $in: [ 'a', 'b', 'c' ] } }
{ field: { $nin: [ 'x', 'y', 'z' ] } }
{ field: { $gt: 10 } }
{ field: { $gt: 13, $lte: 30 } }
{ field: { $gt: Date("2020-01-01"), $lt: Date("2020-03-31") } }

The selectionFilter document can have several key and value filters. For example, if a mark of a multi-series chart is clicked, the filter document contains both the category and series filter pairs. Each filter must reference the actual data source fields used and not their labels.

You can enable highlighting for clicked events using the setHighlight method.

Example

const eventHandler = (payload) => {
  chart.setHighlight(payload.selectionFilter);
};
chart.render(container).then(() => {
  chart.addEventListener('click', eventHandler);
});

To learn more, see Highlight Chart Elements.

On an embedded chart that includes event handlers with a filter for element roles, the chart shows:

The when you hover over an element that triggers a filtered click event
The when you hover over an element that doesn't trigger a click event

If the event handler doesn't include filter for element roles, the appears when you hover over any chart element.

`target` Element

The target element of the payload contains information about the clicked target including:

The type of mark, such as rect, line, arc, symbol, group, or area
The role of mark, such as mark, legend, axis-label, axis-title, tick-label, legend-entry, legend-title, or frame
The fill color of the mark

For tables, the Charts Embedding JavaScript SDK click event handler payload captures the following:

Mark type, which is text
Mark role, such as group-cell, value-cell, dynamic-value-cell, row-total-cell, column-total-cell, header-column-total-cell, and grand-total-cell

For geospatial charts, the Charts Embedding JavaScript SDK click event handler payload captures the following:

The type of mark, such as polygon, map, or symbol
The role of mark, such as mark or map
The fill color of the mark

The Charts Embedding JavaScript SDK click event handler does not capture click events on column headers.

Examples

The Charts Embedding JavaScript SDK includes examples that demonstrate common uses for click events in an application. The first example shows basic click events and payload handling. The second example shows interactive filtering of clicked chart elements.

To learn more about installing the Embedding SDK and running the example app with your own data or sample data, see Atlas Charts Embedding Example for Click Events on GitHub. Each example app is configured with a chart ID and base URL which are particular to the app. Be sure to configure your own apps with the correct chart ID and base URL.

Basic Handling of Click Events

In the example app for basic handling of click events, when you click on an element on the Movie Genres chart, the click event handler displays data based on the clicked element. In this example application, the chart shows the on all chart elements because the chart doesn't include a filter for mark roles.

Each time you click on an element in the chart, the click event listener refreshes the payload to reflect data from the x and y axis. When you click on an element that represents a specific genre and decade in the Movie Genres chart, the Clicked Element and Full Event Payload displays details on that movie genre and decade including:

Fields that represent data for the clicked element.
Mark type, role, and fill color.

Refer to the example app to view the full event payload.

Interactive Filtering for Click Events

In the example app for interactive filtering, when you click on an element on the Movie Genres chart, the embedding SDK generates a filter based on the element on which you clicked and then applies the filter to a second chart. In this example application, the chart shows:

The when you hover over an interactive element
The when you hover over an element which doesn't trigger a click event

The click event listener triggers events only for the mark roles specified through the options parameter. The payload defines a filter based on the y axis, which represents the movie genres, and the lower and upper bound range, which represents the decade. Each time you click on an element that represents a specific genre and decade on the Movie Genres chart, the Movie Details table is filtered by the clicked element and changes to display the movies available in that genre and decade.

Refer to the example app to view the full a sample event handler callback function.

Back

Configure Authentication Providers

Highlight Chart Elements

Note

Prerequisites

Click Event Syntax

Example

Note

Payload

Example

event Element

data Element

selectionFilter Element

Example

Example

target Element

Examples

Basic Handling of Click Events

Interactive Filtering for Click Events

`event` Element

`data` Element

`selectionFilter` Element

`target` Element