/ S

This page covers a next version of Handsontable, and is not published yet.

This page covers a non-latest version of Handsontable.

# Selection

Table of contents

# Overview

Selection enables you to select a single cell or ranges of cells within Handsontable. Once selected, you can retrieve data from the cell, edit the cell's contents, or change the style of the cell.

# Basic configuration

With this feature, you can select single cells or ranges of cells across a grid. Easily retrieve the coordinates of the selected cells to clear or change the cells' content.

Use CMD on Mac or CTRL on Windows to select non-contiguous ranges of cells.

# Selecting ranges

There are different modes in which you can use this plugin. Choose between selecting a single cell, a range of adjacent cells, and multiple ranges of non-contiguous cells.

Possible values of selectionMode:

  • single - A single cell can be selected.
  • range - Multiple cells within a single range can be selected.
  • multiple - Multiple non-contiguous ranges of cells can be selected.
const container = document.querySelector('#example1');
const selectOption = document.querySelector('#selectOption');

const hot = new Handsontable(container, {
  data: Handsontable.helper.createSpreadsheetData(10, 10),
  width: 'auto',
  height: 'auto',
  colWidths: 100,
  rowHeights: 23,
  rowHeaders: true,
  colHeaders: true,
  selectionMode: 'multiple', // 'single', 'range' or 'multiple',
  licenseKey: 'non-commercial-and-evaluation'
});

selectOption.addEventListener('change', event => {
  const value = event.target.value;
  const first = value.split(' ')[0].toLowerCase();

  hot.updateSettings({
    selectionMode: first
  });
});

# Getting data from the selected ranges

To retrieve the selected cells as an array of arrays, you should use the getSelected() or getSelectedRange() methods.

const container = document.querySelector('#example2');
const output = document.querySelector('#output');
const getButton = document.querySelector('#getButton');

const hot = new Handsontable(container, {
  data: Handsontable.helper.createSpreadsheetData(10, 10),
  width: 'auto',
  height: 'auto',
  colWidths: 100,
  rowHeights: 23,
  rowHeaders: true,
  colHeaders: true,
  outsideClickDeselects: false,
  selectionMode: 'multiple', // 'single', 'range' or 'multiple',
  licenseKey: 'non-commercial-and-evaluation'
});

getButton.addEventListener('click', event => {
  const selected = hot.getSelected() || [];
  const data = [];

  for (let i = 0; i < selected.length; i += 1) {
    const item = selected[i];

    data.push(hot.getData(...item));
  }

  output.innerText = JSON.stringify(data, null, 2);
});

# Modifying the selected cells

You may want to delete, format, or otherwise change the selected cells. For example, you can change a value or add CSS classes to the selected cells using the demo below.

const container = document.querySelector('#example3');
const buttons = document.querySelector('#buttons');

const hot = new Handsontable(container, {
  data: Handsontable.helper.createSpreadsheetData(10, 10),
  width: 'auto',
  height: 272,
  colWidths: 100,
  rowHeights: 23,
  rowHeaders: true,
  colHeaders: true,
  outsideClickDeselects: false,
  selectionMode: 'multiple', // 'single', 'range' or 'multiple',
  licenseKey: 'non-commercial-and-evaluation'
});

buttons.addEventListener('click', event => {
  const selected = hot.getSelected() || [];
  const target = event.target.id;

  hot.suspendRender();

  for (let index = 0; index < selected.length; index += 1) {
    const [row1, column1, row2, column2] = selected[index];
    const startRow = Math.max(Math.min(row1, row2), 0);
    const endRow = Math.max(row1, row2);
    const startCol = Math.max(Math.min(column1, column2), 0);
    const endCol = Math.max(column1, column2);

    for (let rowIndex = startRow; rowIndex <= endRow; rowIndex += 1) {
      for (let columnIndex = startCol; columnIndex <= endCol; columnIndex += 1) {
        if (target === 'set-data-action') {
          hot.setDataAtCell(rowIndex, columnIndex, 'data changed');
        }

        if (target === 'add-css-class-action') {
          hot.setCellMeta(rowIndex, columnIndex, 'className', 'c-red');
        }
      }
    }
  }

  hot.render();
  hot.resumeRender();
});

# Styling the selection area

The background color can be easily changed using CSS styles. The main, light blue background color is defined in the .area class.

For non-contiguous selection, multiple classes are making each level a bit darker. These classes are called area-1, area-2, etc.

Unfortunately, there is no easy way to change the border color of the selection.

# Jumping across the grid's edges

When you use keyboard navigation, and you cross an edge of the grid, you can set cell selection to jump to the opposite edge.

# Jumping across vertical edges

To enable jumping across the left and right edges:

To jump across a vertical edge:

  • When cell selection is on a row's first cell, press the left arrow key.
  • When cell selection is on a row's last cell, press the right arrow key, or press TAB.

# Jumping across horizontal edges

To enable jumping across the top and bottom edges:

To jump across a horizontal edge:

  • When cell selection is on a column's first cell, press the up arrow key.
  • When cell selection is on a column's last cell, press the down arrow key, or press ENTER.

← Merge cells →