Skip to main content

Data Selection

Using data point and series selection.

Selection

Data point selection and data series selection provides an easy, visually intuitive way to select data. Enabling users to click a chart rather than selecting items from a multi-select dropdown, or depending on a hidden right-click context menu, provides a rich interactive experience. The selection API is designed with extensive flexibility and ease of use, so you can come up with your own creative ways to select data points or series.

You can read or set either series.selected or point.selected properties through the options() function in order to customize the behavior and interface with selected data points or series.

Some example uses for data selection:

  • Interactive Master Detail Chart Sample
    You can use selection to interact with individual data points to create a master detail chart. For example, select a single month from column data points for Jan-Dec. A second chart linked to this selection can show the daily data for the selected month.
  • Master Detail Calendar Chart Sample
    Select multiple points to compare them in detail.
  • Master Detail Map Sample
    Another scenario is a map of US states allowing users to select one or multiple state points. Once selected, you can show detailed information about these states.
  • Interactive Line Selection Sample
    Pair a dropdown with chart selection to offer a dual selection UI. In effect muting all series except the selected one.
  • Point Selection Limit Sample
    Limit selection to two items that are then compared in another view.

Selection Modes

You can set the series.pointSelection property to specify the selection mode using these options:

  • true or 'auto'
    Selects a single data point when clicked. Ctrl-click (command-click on a Mac) a data point to select more than one. When legend entries with checkboxes are enabled, click or tap the entries to select multiple items. This allows mobile users a way to select a single point by tapping it, or multiple points by tapping entries.
  • 'single'
    Selects only one point at a time. The ctrl modifier will not allow multiple items to be selected and legend entry checkboxes will be represented by radio buttons.
  • 'multiple'
    Allows selecting multiple points. Click or tap points and legend entry checkboxes to select and clear them. Each point must be cleared individually if needed. However, a clear all option can be added to the chart with the code listed below.
  • {max: (number)}
    Limit the number of selected items. The selected items will not exceed the specified count. They will be added and removed as first-in, first-out.

Clear all button


	{ toolbar_items:{ 'Clear All':{ position:'inside top left', events_click: function(){
	// Clear all points
	this.chart.series().points().options({selected:false});
	// Or clear all series and points
	this.chart .series().options({ selected: false }) .points().options({ selected: false }); } } }

Related Properties

  • point.states.select.enabled
    The chart will avoid calculating state styles for the select state to improve performance based on other properties. You can prevent or force the select state styles to be generated for points using this property.
  • series.mouseTracking.enabled
    Specifies whether the series will respond to any mouse events or touch events.

Selection events

In order to respond to chart selection changes, these two event properties are most practical to use.

An array of points or series is passed to the event handler as an argument. There is a slight delay when these events occur in order to make sure all items that are selecting or clearing selection can finish and so this event does not get triggered multiple times needlessly.

JSC.Chart("divId", {
  events: {
    pointSelectionChanged: function(points) {
      console.log(points.map(p => p.name));
    }
  }
});

Selection Styling

Use the point.states.select or series.states.select properties to specify styling to use when points are selected.

JSC.Chart("divId", {
  defaultSeries: {
    states_select: {
      // Selected line series will be thicker
      line_width: 3
    },
    defaultPoint: {
      states_select: {
        // Selected point visuals will have a width of 4px
        outline_width: 4
      }
    }
  }
});

Selection Legend Checkboxes

While tooltips show additional information when hovering data points, you can add point data labels to the legend as well. Enable legend entry checkboxes and series point selection to automatically manage data point selection with legend entry checkboxes and clicking on points.

Example:

{
  defaultSeries: { palette: "default", pointSelection: "multiple" },
  defaultPoint_legendEntry_checkbox_enabled: true
}

The default series legend entry behavior is to toggle visibility and checkboxes will reflect visibility. You can modify this functionality so that checkboxes represent data series selection.

See sample Series Selection Checkbox Sample

Related properties

  • Series with a palette setting like 'default' or (num) will use a unique color for each point and thereby add a legend entry for each point to the legend in place of the series legend entry.
  • Enable checkboxes for legend entries.

This example uses checkboxes to select points and includes a check/clear all checkbox in the legend using a custom legend entry.

See the Pen Docs v3 - Legend Checkbox All by Arthur Puszynski (@jsblog) on CodePen.

Series vs Point states

Both series and points can have mute and selection states, however, series level select states can't be visualized with most series types because they lack a series level visual. For example, area and line series have series level visuals: the line and area fill. They can also have point level visuals: point markers. On the other hand, a marker series has the point visuals but no line. In these cases, selecting a series can apply the select state to all points in order to visualize it. The select state can be used with series whether it can be seen or not.

Selected series and selected points are separate states. A series that is selected does not mean all the points within the series are selected. Series.pointSelection options provide a UI for users to select points, however, series level selection can be managed within chart options with relatively simple code.

This example lets you click a column to select a series and all of its points or to clear the selection. All points are selected to visually show the series is selected.

JSC.Chart("divId", {
  defaultPoint_events_click: function() {
    var point = this,
      series = point.series,
      isSelected = !series.options("selected");

    series.options({ selected: isSelected });
  }
});

Sync point select states with parent series select state. This code iterates over each data point and sets the point selected property based on its parent series selected value.


chart.series().points().each(p=>p.options({selected:p.series.options('selected')});

Programmatic Handling

You can easily detect which series or points are selected and to set the selected states manually.

Set select states

These code snippets apply a selected state programmatically.

// Select all points of the first series
var points = chart
  .series(0)
  .points()
  .options({ selected: true });
// Select first point of first series
var point = Chart.series(0)
  .points(0)
  .options({ selected: true });
Note: When you set a state option through the point or series options() function and apply only the one state property, the internal data flow is very efficient even with many points.

Get and set select states

Getting a list of points or series that are selected can be done with code such as:

// Get a collection of all selected series
chart.series(s => s.options("selected"));
// Get a collection of all selected points.
chart.series().points(p => p.options("selected"));