JavaScript Data Grid Migrating from 11.1 to 12.0

JavaScript Data GridMigrate from 11.1 to 12.0

Migrate from Handsontable 11.1 to Handsontable 12.0, released on April 28, 2022.

On this page

Step 1: Verify your updateSettings() calls

Handsontable 12.0.0 changes how the updateSettings() method handles your grid's data.

Each updateSettings() call with the data option defined:

Before After
Replaces data Replaces data
Triggers the same hooks as loadData() Triggers the same hooks as updateData()
Resets configuration options to the initial state Doesn't reset configuration options to the initial state
Resets index mapper information Doesn't reset index mapper information

Migrating to Handsontable 12.0

If you need to reset your index mapper information and configuration options along with updating your data:

// Handsontable 12.0: this doesn't reset your configuration options and index mapper information
hotInstance.updateSettings({
  data: newDataset
});

// Handsontable 12.0: this does reset your configuration options and index mapper information
hotInstance.loadData(newDataset);

Framework wrappers

Updating your data through a component property no longer resets your index mapper information and configuration options.

To replace data and reset the states, call the loadData() method (the same way as above), referencing the Handsontable instance from the component.

Read more on referencing the Handsontable instance:

Step 2: Adjust to the updatePlugin() changes

Handsontable 12.0.0 changes how the updatePlugin() method reacts to updateSettings() calls.

This change might affect your custom plugins.

Before

Every updateSettings() call (even with an empty object passed as new settings) triggered the updatePlugin() method for each enabled plugin.

As a result, whenever you called updateSettings(), all enabled plugins got updated.

After

A plugin's updatePlugin() method gets triggered only when the object passed to updateSettings() contains at least one of the following:

  • The plugin's PLUGIN_KEY (the plugin's main alias)
  • An entry from the plugin's SETTING_KEYS (a property that stores all additional settings relevant to the plugin)

As a result, a plugin gets updated only if you update settings related to that particular plugin.

Migrating to Handsontable 12.0

If you want your custom plugin to still get updated on every updateSettings() call, set your plugin's SETTING_KEYS to true:

static get SETTING_KEYS() {
  return true;
}

However, in most cases, it's better to provide an explicit list of configuration options that your custom plugin observes. For details, see the Plugins guide.

Step 3: Adjust to the afterDocumentKeyDown changes

Handsontable 12.0.0 changes how the afterDocumentKeyDown hook works.

Before

When you used a keyboard to navigate an internal Handsontable instance (e.g., a context menu), the afterDocumentKeyDown hook got fired on every key press.

afterDocumentKeyDown() {
  // when you navigate the grid, the console message gets logged on every key press
  // when you navigate the context menu, the console message also gets logged on every key press
  console.log('key pressed');
}

After

When you use a keyboard to navigate some internal instances of Handsontable (e.g., a context menu), the afterDocumentKeyDown hook may not get fired anymore.

afterDocumentKeyDown() {
  // when you navigate the grid, the console message gets logged on every key press
  // when you navigate the context menu, the console message doesn't get logged at all
  console.log('key pressed');
}

This change may affect the following areas of Handsontable:

Migrating to Handsontable 12.0

You can't change this behavior by using any of Handsontable's APIs.

Step 4: Adjust to the default keyboard shortcuts changes

TIP

These changes don't affect your custom keyboard shortcuts.

Handsontable 12.0 introduces a new keyboard shortcuts API, ShortcutManager.

ShortcutManager lets you easily manage your custom keyboard shortcuts, but also changes how Handsontable defines its default keyboard shortcuts. Now, nearly all default keyboard shortcuts are defined explicitly.

We took this opportunity to improve the behavior of Handsontable's default keyboard shortcuts, so they:

  • Better match their counterparts in popular spreadsheet software
  • Improve the consistency of keyboard navigation
  • Create a more intuitive user experience

Ctrl vs Cmd

Handsontable 12.0 splits a cross-platform modifier key (Ctrl/Cmd) into two separate keys. Now, the Cmd key triggers actions on macOS where the Ctrl key triggers actions on Windows.

For example, the table below shows how this change affects the Ctrl/Cmd+A shortcut:

Before After
Windows Ctrl+A works
Cmd+A works		 Only Ctrl+A works
macOS Ctrl+A works
Cmd+A works		 Only Cmd+A works

TIP

The default keyboard shortcut for merging cells is an exception: Cmd+M doesn't work anymore, as it conflicted with macOS's shortcut for window minimizing.

Keyboard shortcuts changes: Navigation

The table below summarizes default keyboard shortcuts changes related to navigation:

Windows macOS Before After
Ctrl+↑ Cmd+↑ Extend the selection by one cell up Move to the first cell of the current column
Ctrl+↓ Cmd+↓ Extend the selection by one cell down Move to the last cell of the current column
Ctrl+← Cmd+← Extend the selection by one cell to the left Move to the leftmost cell of the current row
Ctrl+→ Cmd+→ Extend the selection by one cell to the right Move to the rightmost cell of the current row
Home Home Move to the first cell of the current row Move to the first non-frozen cell of the current row*
Ctrl+Home Cmd+Home Move to the first cell of the current column Move to the first non-frozen cell of the grid*
End End Move to the last cell of the current row Move to the last non-frozen cell of the current row*
Ctrl+End Cmd+End Move to the last cell of the current column Move to the last non-frozen cell of the grid*

* This action depends on your layout direction.

Keyboard shortcuts changes: Selection

The table below summarizes default keyboard shortcuts changes related to selection:

Windows macOS Before After
Ctrl+Shift+↑ Cmd+Shift+↑ Extend the selection by one cell up Extend the selection to the first cell of the current column**
Ctrl+Shift+↓ Cmd+Shift+↓ Extend the selection by one cell down Extend the selection to the last cell of the current column**
Ctrl+Shift+← Cmd+Shift+← Extend the selection by one cell to the left Extend the selection to the leftmost cell of the current row**
Ctrl+Shift+→ Cmd+Shift+→ Extend the selection by one cell to the right Extend the selection to the rightmost cell of the current row**
Ctrl+Shift+Home Cmd+Shift+Home Extend the selection to the first cell of the current column Doesn't work anymore (replaced by Ctrl/Cmd+Shift+↑)
Ctrl+Shift+End Cmd+Shift+End Extend the selection to the last cell of the current column Doesn't work anymore (replaced by Ctrl/Cmd+Shift+↓)
Shift+Page Up Shift+Page Up Move one screen up Extend the selection by one screen up
Shift+Page Down Shift+Page Down Move one screen down Extend the selection by one screen down
Ctrl+Enter Cmd+Enter Enter the editing mode of the active cell Fill the selected range of cells with the value of the active cell

** In case of multiple selection layers, only the last selection layer gets extended.

Keyboard shortcuts changes: Edition

The table below summarizes default keyboard shortcuts changes related to edition:

Windows macOS Before After
Home Home Native browser behavior for the entire window Move the cursor to the beginning of the text*
End End Native browser behavior for the entire window Move the cursor to the end of the text*
Ctrl+Z Cmd+Z Undo the last action Undo the last action in the cell editor
Ctrl+Shift+Z Cmd+Shift+Z Redo the last action Redo the last action in the cell editor
Shift+Page Up Shift+Page Up Move one screen up Doesn't work when editing a cell
Shift+Page Down Shift+Page Down Move one screen down Doesn't work when editing a cell

* This action depends on your layout direction.

Keyboard shortcuts changes: Cell merging

The table below summarizes default keyboard shortcuts changes related to cell merging:

Before After
Windows Ctrl+M works Cmd+M works Only Ctrl+M works
macOS Ctrl+M works Cmd+M works Only Ctrl+M works
(Cmd+M conflicted with macOS's shortcut for window minimizing)

Migrating to Handsontable 12.0

To keep the previous (pre-12.0) behavior of a default keyboard shortcut, use the new ShortcutManager API to:

Step 5: Avoid referring to _wt

Handsontable 12.0.0 makes it clear that Handsontable's rendering engine (_wt, internally referred to as "Walkontable") is not a part of Handsontable's public API.

To emphasize this, we changed the following property name:

Before After
handsontableInstance.view.wt handsontableInstance.view._wt

Migrating to Handsontable 12.0

_wt has no public documentation and offers no guarantee against breaking changes.

If you use a private implementation of Handsontable, and you can't avoid referring to Walkontable (for example, in your custom editor or plugin), update your Walkontable references from handsontableInstance.view.wt to handsontableInstance.view._wt.

TIP

New method: getEditedCellRect()

If your custom editor needs to know the size and position of the edited cell, now you can get them without referring to _wt. Instead, use the new getEditedCellRect() method.