JavaScript ChartsData Selection

Data Selection allows users click or drag on the chart to mark individual datums as selected. Selected datums receive a distinct visual treatment and can be read back, set, or cleared programmatically.

Selection Copy Link

To enable this feature, set selection.enabled to true.

{
    selection: {
        enabled: true,
        enableDrag: true,
    },
}

Selection can also be configured independently on each series via the series.selection options.

Click Selection Copy Link

Click selection is enabled by default. Use enableClick: false to disable.

By default, clicking a datum replaces the current selection, and clicking on a blank space clears the selection. Use clickMode and enableClickAwayToClear to modify this behaviour.

{
    selection: {
        enabled: true,
        clickMode: 'single',
        enableClickAwayToClear: true,
    },
}

In the above example:

• 'single' replaces the current selection with the clicked datum.
• 'multiple' toggles the clicked datum in or out of the existing selection. This mode is particularly useful on touch devices.
• Holding ^ Ctrl⌘ Command key while clicking will always add or remove the clicked datum from the selection.
• When enableClickAwayToClear is set to false, the selection remains in place when the user clicks an empty area of the chart.
• Click range is determined by the nodeClickRange property on each series type.

Drag-to-Select Copy Link

Set enableDrag to true to allow the user draw a rectangle across the chart and select every datum the rectangle covers. This is only available on cartesian series types.

{
    selection: {
        enabled: true,
        enableDrag: true,
        containment: 'any',
    },
}

In the above example:

• Dragging the mouse across the chart draws a rectangle. When the mouse is released, any datums that overlap the rectangle are selected.
• Holding ^ Ctrl⌘ Command key while completing a drag adds the newly enclosed datums to the existing selection instead of replacing it.
• The containment option controls which datums the drag rectangle picks up.
  • 'any' (default) selects a datum if any part of it overlaps the drag rectangle.
  • 'all' selects a datum only when it is entirely enclosed by the drag rectangle.

Styling Copy Link

Use the series series.selection.selectedItem and series.selection.unselectedItem options to customise the appearance of selected and unselected datums.

{
    series: [
        {
            type: 'bar',
            xKey: 'quarter',
            yKey: 'revenue',
            selection: {
                selectedItem: {
                    fill: '#c0392b',
                    stroke: '#922b21',
                    strokeWidth: 3,
                },
                unselectedItem: {
                    fill: '#bdc3c7',
                    fillOpacity: 0.6,
                },
            },
        },
    ],
}

In this example:

• selectedItem sets the selected datum to a red fill and border.
• unselectedItem sets the unselected datums to a grey fill.
• For dynamic per-datum styling, use the series item styler, which includes a selectionState property in the parameters.

Candidacy Copy Link

The candidateState property in Styler callbacks can be used to customise the styling while a drag motion is in progress based on the pending selection state.

In this example:

• When no dragging is in progress:
  • Selected bars are rendered in 'skyblue' colour.
  • Unselected bars are dimmed.
• When dragging is in progress:
  • Bars that will be added to the selection are rendered in 'green' colour.
  • Bars that will be removed from the selection are rendered in 'red' colour.

The candidateState property includes:

• undefined - no drag selection is in progress.
• 'selected-item' - the datum will become selected after the drag completes.
• 'unselected-item' - the datum will become unselected after the drag completes.
• 'none' - there will be nothing selected after the drag completes.

Once the drag completes, the candidateState becomes the new selectionState. If the user cancels the drag, the candidateState is cleared and the selectionState remains unchanged.

Selection API Copy Link

Saving and Restoring Copy Link

chart.getSelection() returns an Iterable of every currently selected item. Each item contains:

• seriesId- the series the datum belongs to.
• itemId - the unique identifier of the datum, derived from dataIdKey if set, otherwise the datum index.
• datum - the original data object from the chart data array.

chart.setSelection(items) replaces the current selection. Each item requires seriesId and itemId to identify the datum. The existing selection is cleared before the new items are applied.

chart.clearSelection() removes every selected item across all series.

Selection Change Event Copy Link

The selectionChange event fires whenever the selection is updated, whether by user interaction or an API call.

{
    listeners: {
        selectionChange: (event) => {
            console.log(event.source, event.added, event.removed);
        },
    },
}

The event contains:

• source - 'user-interaction' or 'api-call'.
• added - an array of items added to the selection.
• removed - an array of items removed from the selection.

Feature Interactions Copy Link

Highlighting Copy Link

When both selection and highlighting are enabled, the chart merges their visual styles. If there is a conflict, the selection style takes priority.

Zoom Copy Link

When both selection drag and zoom drag-to-select (enableSelecting) are enabled, the selection drag takes precedence. Zoom panning uses the panKey modifier instead. See Zoom Panning for details.

API Reference Copy Link