/ S

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

This page covers a non-latest version of Handsontable.

# Setting options

Table of contents

# Overview

Handsontable uses cascading configuration, a fast way to provide configuration options for the entire table, including its columns and particular cells. To show you how it works, we use the readOnly and className options.

# Entire grid

By setting the readOnly option, we propagate the option through the column settings down to the cells. As a result, all cells have a read-only state.

    # Single column

    Moving on, let's set the read-only cells by setting the option for columns.

      # Single row

      Using the cells option we can apply read-only option to entire rows. In the example below, the second and last rows are read-only.

        # Single cell

        And finally, let's make one of the cells read-only.

          # cells vs cell

          In the Options section of the API, you can find two similar options, cell and cell. Using one of these options (or both), you can associate the custom properties or overwrite an entire table or column option for a particular cell. Both options allow you to set initial values for specific cells. You can check if the values are propagated by calling the getCellMeta method. The method returns an object with all built-in options as well as those added by the developer.

          # cell

          The cell option works great for cases when you have to set initial values for your custom properties or change the initial values for the built-in option. Once the changes are propagated to the cells' meta-objects, they can be modified by the Handsontable while it is running. For example, the cell read-only state can be modified by the context menu.

          // ...
cell: [
  { row: 1, col: 1, readOnly: true, className: 'bg-read-only' }
],
// ...

hot.getCellMeta(0, 0).readOnly === false; // By default the option is "false"
hot.getCellMeta(1, 1).readOnly === true; // the "cell" overwrites the value

// The state can be changed using API or UI e.g.
hot.setCellMeta(1, 1, 'readOnly', false);

          # cells

          The cells option works slightly differently. The cells option is a function that invokes the logic in it before the table's rendering cycle. The options returned by that function always overwrite the entire table or column options. Thus, if you implement logic incorrectly, you won't be able to change cells' state from API or UI - as the values will be constantly overwritten by the cells function. You can think of this option as an opportunity to transfer the responsibility of keeping the table cells option to your application.

          If at some point you want to stop overwriting the cell meta object for particular cells, return an empty object, null or undefined value.

          // ...
cells(row, column) {
  if (row === 1 && column === 1) {
    return {
      readOnly: true,
      className: 'bg-read-only'
    };
  }
},
// ...

hot.getCellMeta(0, 0).readOnly === false; // By default the option is "false"
hot.getCellMeta(1, 1).readOnly === true; // the "cells" overwrites the value

// In this case, an attempt to change the state will have no effect. The `readOnly`
// property always returns `true`.
hot.setCellMeta(1, 1, 'readOnly', false);

          # Show time

          With a combination of the above configuration layers, you're able to manage a more complex setup.

          Consider the following example:

            The above snippet makes all cells read-only, except the first column, which remains editable. However, notice how the top-left cell, as well as the cell at index 3, 3 are still read-only. It's because their properties are individually managed within the cells option.

            # All options

            The most up to date list of options is available in the Options section of the API Reference.

            ← Grid size →