Checkbox cell type
Create interactive elements that can be checked or unchecked, by using the checkbox cell type.
The checkbox cell type renders a boolean value as a clickable checkbox. Use it for yes/no, active/inactive, or any true/false data.
Overview
Data in these cells will be rendered as a checkbox and you can easily change it by checking/unchecking the checkbox.
To check the box, use the mouse or press Space or Enter.
To uncheck the box, use the mouse or press Space, Enter, Delete or Backspace.
You can change the state of multiple cells at once by selecting the cells you want to change and pressing Space. Selecting a column header, a row header, or the corner selects the cells under it. Press Space to change those checkboxes, also when navigableHeaders is enabled.
To let users select whole rows with checkboxes and a “select all” checkbox, without storing the checked state in your data, use row selection instead.
Checkbox true/false values
This is the default usage scenario where column data has a true or false value, and we only want to display checkboxes.
import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const container = document.querySelector('#example1');
new Handsontable(container, { data: [ { car: 'Mercedes A 160', year: 2017, available: true, comesInBlack: 'yes' }, { car: 'Citroen C4 Coupe', year: 2018, available: false, comesInBlack: 'yes', }, { car: 'Audi A4 Avant', year: 2019, available: true, comesInBlack: 'no' }, { car: 'Opel Astra', year: 2020, available: false, comesInBlack: 'yes' }, { car: 'BMW 320i Coupe', year: 2021, available: false, comesInBlack: 'no' }, ], colHeaders: ['Car model', 'Year of manufacture', 'Available'], height: 'auto', columns: [ { data: 'car', }, { data: 'year', type: 'numeric', }, { data: 'available', type: 'checkbox', }, ], autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const container = document.querySelector('#example1')!;
new Handsontable(container, { data: [ { car: 'Mercedes A 160', year: 2017, available: true, comesInBlack: 'yes' }, { car: 'Citroen C4 Coupe', year: 2018, available: false, comesInBlack: 'yes', }, { car: 'Audi A4 Avant', year: 2019, available: true, comesInBlack: 'no' }, { car: 'Opel Astra', year: 2020, available: false, comesInBlack: 'yes' }, { car: 'BMW 320i Coupe', year: 2021, available: false, comesInBlack: 'no' }, ], colHeaders: ['Car model', 'Year of manufacture', 'Available'], height: 'auto', columns: [ { data: 'car', }, { data: 'year', type: 'numeric', }, { data: 'available', type: 'checkbox', }, ], autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});Checkbox template
If you want to use values other than true and false, you have to provide this information using checkedTemplate and uncheckedTemplate. Handsontable DataGrid will then update your data using the appropriate template.
import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const container = document.querySelector('#example2');
new Handsontable(container, { data: [ { car: 'Mercedes A 160', year: 2017, available: true, comesInBlack: 'yes' }, { car: 'Citroen C4 Coupe', year: 2018, available: false, comesInBlack: 'yes', }, { car: 'Audi A4 Avant', year: 2019, available: true, comesInBlack: 'no' }, { car: 'Opel Astra', year: 2020, available: false, comesInBlack: 'yes' }, { car: 'BMW 320i Coupe', year: 2021, available: false, comesInBlack: 'no' }, ], colHeaders: ['Car model', 'Year of manufacture', 'Comes in black'], height: 'auto', columns: [ { data: 'car', }, { data: 'year', type: 'numeric', }, { data: 'comesInBlack', type: 'checkbox', checkedTemplate: 'yes', uncheckedTemplate: 'no', }, ], autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const container = document.querySelector('#example2')!;
new Handsontable(container, { data: [ { car: 'Mercedes A 160', year: 2017, available: true, comesInBlack: 'yes' }, { car: 'Citroen C4 Coupe', year: 2018, available: false, comesInBlack: 'yes', }, { car: 'Audi A4 Avant', year: 2019, available: true, comesInBlack: 'no' }, { car: 'Opel Astra', year: 2020, available: false, comesInBlack: 'yes' }, { car: 'BMW 320i Coupe', year: 2021, available: false, comesInBlack: 'no' }, ], colHeaders: ['Car model', 'Year of manufacture', 'Comes in black'], height: 'auto', columns: [ { data: 'car', }, { data: 'year', type: 'numeric', }, { data: 'comesInBlack', type: 'checkbox', checkedTemplate: 'yes', uncheckedTemplate: 'no', }, ], autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});Values pasted or autofilled into a checkbox
A checkbox cell stores checkedTemplate or uncheckedTemplate whenever a written value matches one of them, regardless of letter case. This applies to pasting, autofill, and API calls such as setDataAtCell(). For example, with the default templates, pasting False stores the boolean false, and pasting TRUE stores true. With checkedTemplate: 'yes', pasting YES stores 'yes'.
A value that matches neither template, such as Ted dragged in with the fill handle, is stored as it is, and the cell shows #bad-value#.
To flag or reject such values, add the built-in checkbox validator. The checkbox cell type doesn’t apply it by default.
columns: [ { type: 'checkbox', // mark values that match neither template as invalid validator: 'checkbox', // reject them instead, and keep the cell's previous value allowInvalid: false, },],With allowInvalid set to true (the default), Handsontable stores the value and adds the htInvalid class to the cell. With allowInvalid: false, Handsontable rejects the value and the cell keeps its previous value. The validator accepts empty values unless you set allowEmpty to false. A template that is itself empty (for example, uncheckedTemplate: '') is always valid.
The checkbox cell type doesn’t register the validator. registerAllModules() does. If you register modules one by one, register the validator too:
import { registerCellType, CheckboxCellType } from 'handsontable/cellTypes';import { registerValidator, checkboxValidator } from 'handsontable/validators';
registerCellType(CheckboxCellType);registerValidator(checkboxValidator);Cells with no value
When a checkbox cell’s value is empty (null, undefined, or an empty string) and matches neither checkedTemplate nor uncheckedTemplate, Handsontable renders an unchecked checkbox and adds a noValue CSS class to it.
By default, the noValue class reduces the checkbox’s opacity, so cells with no value look faded and stay visually distinct from cells set to the unchecked value.
To change how these cells look, target the noValue class in your CSS. The checkbox’s tick is a separate <i class="ht-icon"> element placed right after the input, so style it through the + combinator:
.handsontable .htCheckboxRendererInput.noValue,.handsontable .htCheckboxRendererInput.noValue + .ht-icon { opacity: 1;}Checkbox labels
To add a label to the checkbox, use the label option. You can declare where the label will be injected with this option - either before or after the checkbox element. You can also declare from which data source the label text will be updated.
import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const container = document.querySelector('#example3');
new Handsontable(container, { data: [ { car: 'Mercedes A 160', year: 2017, available: true, comesInBlack: 'yes' }, { car: 'Citroen C4 Coupe', year: 2018, available: false, comesInBlack: 'yes', }, { car: 'Audi A4 Avant', year: 2019, available: true, comesInBlack: 'no' }, { car: 'Opel Astra', year: 2020, available: false, comesInBlack: 'yes' }, { car: 'BMW 320i Coupe', year: 2021, available: false, comesInBlack: 'no' }, ], colHeaders: ['Car model', 'Accepted', 'Comes in black'], height: 'auto', columns: [ { data: 'car', }, { data: 'available', type: 'checkbox', label: { position: 'after', property: 'car', // Read value from row object }, }, { data: 'comesInBlack', type: 'checkbox', checkedTemplate: 'yes', uncheckedTemplate: 'no', label: { position: 'before', value: 'In black? ', }, }, ], autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const container = document.querySelector('#example3')!;
new Handsontable(container!, { data: [ { car: 'Mercedes A 160', year: 2017, available: true, comesInBlack: 'yes' }, { car: 'Citroen C4 Coupe', year: 2018, available: false, comesInBlack: 'yes', }, { car: 'Audi A4 Avant', year: 2019, available: true, comesInBlack: 'no' }, { car: 'Opel Astra', year: 2020, available: false, comesInBlack: 'yes' }, { car: 'BMW 320i Coupe', year: 2021, available: false, comesInBlack: 'no' }, ], colHeaders: ['Car model', 'Accepted', 'Comes in black'], height: 'auto', columns: [ { data: 'car', }, { data: 'available', type: 'checkbox', label: { position: 'after', property: 'car', // Read value from row object }, }, { data: 'comesInBlack', type: 'checkbox', checkedTemplate: 'yes', uncheckedTemplate: 'no', label: { position: 'before', value: 'In black? ', }, }, ], autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});Label value as a function
The value property of the label option can also be a function. The function receives four arguments: row, column, prop, and value, where value is the current cell value. This lets you generate label text dynamically based on the cell’s state.
import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const container = document.querySelector('#example4');
new Handsontable(container, { data: [ { car: 'Mercedes A 160', year: 2017, comesInBlack: 'yes' }, { car: 'Citroen C4 Coupe', year: 2018, comesInBlack: 'yes' }, { car: 'Audi A4 Avant', year: 2019, comesInBlack: 'no' }, { car: 'Opel Astra', year: 2020, comesInBlack: 'yes' }, { car: 'BMW 320i Coupe', year: 2021, comesInBlack: 'no' }, ], colHeaders: ['Car model', 'Year', 'Comes in black'], height: 'auto', columns: [ { data: 'car', }, { data: 'year', }, { data: 'comesInBlack', type: 'checkbox', checkedTemplate: 'yes', uncheckedTemplate: 'no', label: { position: 'after', value(row, column, prop, value) { if (value === 'yes') { return 'In black'; } else { return 'Not in black'; } }, }, }, ], autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const container = document.querySelector('#example4')!;
new Handsontable(container, { data: [ { car: 'Mercedes A 160', year: 2017, comesInBlack: 'yes' }, { car: 'Citroen C4 Coupe', year: 2018, comesInBlack: 'yes' }, { car: 'Audi A4 Avant', year: 2019, comesInBlack: 'no' }, { car: 'Opel Astra', year: 2020, comesInBlack: 'yes' }, { car: 'BMW 320i Coupe', year: 2021, comesInBlack: 'no' }, ], colHeaders: ['Car model', 'Year', 'Comes in black'], height: 'auto', columns: [ { data: 'car', }, { data: 'year', }, { data: 'comesInBlack', type: 'checkbox', checkedTemplate: 'yes', uncheckedTemplate: 'no', label: { position: 'after', value(row: number, column: number, prop: string | number, value: string) { if (value === 'yes') { return 'In black'; } else { return 'Not in black'; } }, }, }, ], autoWrapRow: true, autoWrapCol: true, // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/});Check all in the column header
To add a “check all” checkbox to the header of a checkbox column, set the headerCheckbox option on that column.
- A click on the header checkbox checks every cell in the column. When every cell is already checked, it unchecks them.
- When only some cells are checked, the header checkbox shows a mixed state, and a click checks all of them.
- Read-only cells are skipped and aren’t counted.
- The change is one step for undo and redo.
- With the
navigableHeadersoption, focus the header and press Space.
import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const container = document.querySelector('#example5');
new Handsontable(container, { // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/ data: [ { task: 'Update API docs', assignee: 'Ana García', done: true }, { task: 'Deploy hotfix', assignee: 'James Okafor', done: false }, { task: 'Review pull request', assignee: 'Li Wei', done: true }, { task: 'Plan sprint', assignee: 'Ana García', done: false }, { task: 'Fix login bug', assignee: 'James Okafor', done: false }, { task: 'Write release notes', assignee: 'Li Wei', done: false }, ], columns: [ { data: 'task', title: 'Task' }, { data: 'assignee', title: 'Assignee' }, { data: 'done', title: 'Done', type: 'checkbox', // add a "check all" checkbox to the column header headerCheckbox: true, }, ], colHeaders: true, rowHeaders: true, // reach the header checkboxes with the arrow keys, toggle them with Space navigableHeaders: true, height: 'auto', autoWrapRow: true, autoWrapCol: true,});import Handsontable from 'handsontable/base';import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.registerAllModules();
const container = document.querySelector('#example5')!;
new Handsontable(container, { // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/ data: [ { task: 'Update API docs', assignee: 'Ana García', done: true }, { task: 'Deploy hotfix', assignee: 'James Okafor', done: false }, { task: 'Review pull request', assignee: 'Li Wei', done: true }, { task: 'Plan sprint', assignee: 'Ana García', done: false }, { task: 'Fix login bug', assignee: 'James Okafor', done: false }, { task: 'Write release notes', assignee: 'Li Wei', done: false }, ], columns: [ { data: 'task', title: 'Task' }, { data: 'assignee', title: 'Assignee' }, { data: 'done', title: 'Done', type: 'checkbox', // add a "check all" checkbox to the column header headerCheckbox: true, }, ], colHeaders: true, rowHeaders: true, // reach the header checkboxes with the arrow keys, toggle them with Space navigableHeaders: true, height: 'auto', autoWrapRow: true, autoWrapCol: true,});By default, the header checkbox writes to the rows that pass the filters, on every page. To change that, pass a scope:
columns: [ { data: 'done', type: 'checkbox', // 'filtered' (default), 'all' (also rows the filters hide), or 'currentPage' headerCheckbox: { scope: 'currentPage' }, },],To let users select rows rather than edit a value, see Row selection.
Extend the checkbox with a custom renderer
To add your own content to a checkbox cell, write a custom renderer that chains the built-in checkbox renderer and then adds nodes to the cell.
Add those nodes with DOM methods such as appendChild or insertAdjacentText, on the element returned by Handsontable.dom.getCellContentRoot(td). Do not use td.innerHTML += .... Assigning to innerHTML re-serializes and re-parses the whole cell on every draw, which rebuilds the cell’s content wrapper and drops any state that lives only as a DOM property rather than a reflected HTML attribute, as well as any listener attached directly to a node. Your markup string is also parsed as raw HTML, without the sanitization Handsontable applies to the content it renders itself.
The snippet below uses the global Handsontable object. In a framework wrapper, import Handsontable and use Handsontable.renderers/Handsontable.dom the same way.
const baseCheckboxRenderer = Handsontable.renderers.getRenderer('checkbox');
function checkboxWithNoteRenderer(instance, td, row, col, prop, value, cellProperties) { // Render the checkbox first. baseCheckboxRenderer.call(this, instance, td, row, col, prop, value, cellProperties);
// Then add your own content next to it. const contentRoot = Handsontable.dom.getCellContentRoot(td);
contentRoot.appendChild(instance.rootDocument.createTextNode(' (in stock)'));}Register the renderer, or pass it as the column’s renderer option, alongside type: 'checkbox'.
Result
After configuring the checkbox cell type, cells display an interactive checkbox. Clicking the checkbox or pressing Space or Enter toggles its state. The underlying data source stores the boolean value (or your custom checkedTemplate/uncheckedTemplate values).
Non-toggleable checkboxes
A checkbox has no separate editing gesture: clicking the box is the edit. So a checkbox cell with editor set to false or null renders a disabled checkbox. Neither a click nor the keyboard shortcuts below change its value, but you can still select the cell.
This applies to an editor: false set on any configuration level, including the grid level. To keep one checkbox column toggleable in a grid that has editor: false, set editor: true on that column, which keeps the editor the checkbox type provides. Naming it with editor: 'checkbox' works too:
editor: false,columns: [ { data: 'name' }, // toggleable, despite the grid-level `editor: false` { data: 'selected', type: 'checkbox', editor: true }]To make a checkbox non-toggleable and also announce it as read-only to screen readers, use readOnly instead.
With readOnlyStyling set to false, a checkbox with no editor is not rendered disabled. It looks like a toggleable one, the same way a read-only checkbox does under that setting, and a click still doesn’t change its value.
Related keyboard shortcuts
| Windows | macOS | Action | Excel | Sheets |
|---|---|---|---|---|
| Space | Space | Check or uncheck the checkbox | ✗ | ✓ |
| Enter | Enter | Check or uncheck the checkbox | ✗ | ✓ |
| Delete | Delete | Uncheck the checkbox | ✗ | ✓ |
| Backspace | Backspace | Uncheck the checkbox | ✗ | ✓ |
These shortcuts don’t change a cell that is readOnly or has no editor.
For the full list of default keyboard shortcuts, see keyboard shortcuts.
Related articles
Related guides
Configuration options
Core methods
Hooks
Plugins