Row selection

Row selection is available in Highcharts Grid Pro. It lets end users pick one or more rows so your application can act on those records: editing, deleting, exporting, comparing, or driving a connected component such as a Highcharts chart.

Selected rows are highlighted, optionally show a checkbox, and are available through a public API and a pair of events.

Basic configuration

Selection is off by default. Set rowSelection.enabled to turn it on:

Grid.grid('container', {
data: {
columns: {
id: ['row-001', 'row-002', 'row-003'],
product: ['Alpha', 'Beta', 'Gamma']
},
idColumn: 'id'
},
rowSelection: {
enabled: true
}
});

Selection modes

The mode option controls how many rows can be selected at once.

ModeBehavior
single (default)Only one row is selected at a time. Clicking the selected row again deselects it.
multipleSeveral rows can be selected. Shift-click selects a continuous range from the last clicked row.
rowSelection: {
enabled: true,
mode: 'multiple'
}

Click action in the multiple mode

In the multiple mode, clickAction decides what a plain click on the row — not on the checkbox, which always toggles — does:

ValueBehavior
toggle (default)The clicked row is added to, or removed from, the selection. Every row can be picked with a plain click.
replaceThe clicked row replaces the selection. Rows are added or removed with the modifier key instead, the way file managers behave.

modifierKey chooses that modifier. The default, ctrlOrMeta, follows the platform: Command on macOS, Control everywhere else. The alternative is alt. Shift is not available, because it selects a range.

rowSelection: {
enabled: true,
mode: 'multiple',
clickAction: 'replace',
modifierKey: 'ctrlOrMeta'
}

What selects a row

The trigger option controls the interactions that select a row, so row clicks can be enabled or disabled independently of the checkbox.

ValueBehavior
both (default)Clicking anywhere on the row, and clicking the checkbox, both select.
rowOnly clicking the row selects. The checkbox becomes a read-only indicator.
checkboxOnly clicking the checkbox selects. Requires checkbox.enabled.

Clicks that land on an interactive element inside a cell — an input, select, button, a, or textarea — never change the selection, so cell renderers and links keep working.

Keyboard users select the focused row with Space. Enter is reserved for cell editing.

Checkboxes

Set checkbox.enabled to render a checkbox reflecting each row's selected state. By default the checkbox gets its own dedicated column, inserted as the first column:

rowSelection: {
enabled: true,
mode: 'multiple',
checkbox: {
enabled: true
}
}

Use checkbox.columnWidth to change how wide that column is. The dedicated column holds no data, so it is excluded from sorting, filtering, editing, and exporting.

To prepend the checkbox to an existing column instead of adding a new one, name that column with checkbox.columnId:

rowSelection: {
enabled: true,
mode: 'multiple',
checkbox: {
enabled: true,
columnId: 'product'
}
}

Reading the selection

The controller on grid.rowSelection exposes the current selection and lets you change it programmatically:

const grid = await Grid.grid('container', { /* ... */ }, true);
grid.rowSelection.getSelectedRowIds(); // ['row-001', 'row-003']
grid.rowSelection.isSelected('row-001'); // true
grid.rowSelection.select('row-002');
grid.rowSelection.select(['row-002', 'row-003']);
grid.rowSelection.deselect('row-002');
grid.rowSelection.toggle('row-003');
grid.rowSelection.clear();

Row ids come from the data provider — see Row ids below.

Events

Two grid-level events fire around every selection change:

EventDescription
beforeRowSelectionChangeBefore the change is applied. Call event.preventDefault() to cancel it.
afterRowSelectionChangeAfter the change was applied.

Both receive the same payload:

PropertyDescription
addedRowIdsIds of the rows that became selected.
removedRowIdsIds of the rows that became deselected.
selectedRowIdsThe whole selection — before the change on beforeRowSelectionChange, after it on afterRowSelectionChange.
originalEventThe browser event that caused the change, or undefined when the change came from the API.

Each event fires once per gesture, so selecting a range of ten rows produces one event carrying all ten in addedRowIds. Nothing fires when a change would be a no-op.

Driving a chart from the selection

selectedRowIds is all a connected component needs:

Grid.grid('container', {
// ...
rowSelection: {
enabled: true,
mode: 'multiple',
checkbox: { enabled: true }
},
events: {
afterRowSelectionChange: function (e) {
chart.update({
series: e.selectedRowIds.map(id => ({
type: 'line',
name: cities[id].name,
data: cities[id].temperatures
}))
}, true, true);
}
}
});

To cancel a change — for example while a form is dirty — prevent it:

events: {
beforeRowSelectionChange: function (e) {
if (hasUnsavedChanges) {
e.preventDefault();
}
}
}

Row ids

The selection is keyed by row id, not by row position, which is what lets it survive sorting, filtering, and pagination.

Set data.idColumn to a column holding a unique value per row whenever you can. Without it:

  • The local data provider falls back to the row's original position in the source data. That is stable across sorting, filtering, and paging, but not across replacing the dataset.
  • The remote data provider derives ids from positions in the current query result unless the server returns rowIds. Sorting or filtering then moves the selection onto different rows, so data.idColumn is effectively required there — the provider logs a console warning when it has to fall back to positions.

Styling

Selected rows get the hcg-row-selected class. The highlight itself is part of the theme, so it only applies to a themed grid — with rendering.theme: '' the class is still set but nothing is painted, leaving the styling to you.

The checkbox is different: on an unthemed grid it falls back to the native browser checkbox, so it stays visible without any styling. Target it with .hcg-selection-checkbox:

.hcg-selection-checkbox {
accent-color: #7cb5ec;
}

Three CSS variables control the highlight:

VariableDescription
--hcg-row-selected-backgroundThe color blended into the selected row background.
--hcg-row-selected-colorThe text color of a selected row.
--hcg-row-selected-opacityHow strongly the background color is blended in. Falls back to --hcg-hover-opacity, as the hover and sync states do.
.hcg-theme-default {
--hcg-row-selected-background: #7cb5ec;
--hcg-row-selected-opacity: 20%;
}

Cells of the dedicated selection column carry hcg-selection-cell.

Accessibility

Selected rows are marked with aria-selected, and the table is marked aria-multiselectable in the multiple mode. The checkbox label comes from lang.rowSelection.selectRow, so it can be localized:

lang: {
rowSelection: {
selectRow: 'Velg rad'
}
}

Limitations

The dedicated selection column is a normal column, so it scrolls horizontally with the others. If column virtualization is active it can be detached once scrolled out of view. Prepend the checkbox to a column you keep in view, or turn column virtualization off, when that matters.

Demo