This page covers a non-latest version of Handsontable.

# Migrating from 11.1 to 12.0

Step 1: Verify your updateSettings() calls
Step 2: Adjust to the updatePlugin() changes
Step 3: Adjust to the afterDocumentKeyDown changes
Step 4: Adjust to the default keyboard shortcuts changes
Step 5: Avoid referring to _wt

To upgrade your Handsontable version from 11.x.x to 12.x.x, follow this guide.

# 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:

Instead of passing the data option to the updateSettings() method, run loadData() and provide the new dataset as its argument:

// 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.

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.

← Migrating from 10.0 to 11.0

# Migrating from 11.1 to 12.0

# Step 1: Verify your updateSettings() calls

# Migrating to Handsontable 12.0

# Framework wrappers

# Step 2: Adjust to the updatePlugin() changes

# Before

# After

# Migrating to Handsontable 12.0

# Step 3: Adjust to the afterDocumentKeyDown changes

# Before

# After

# Migrating to Handsontable 12.0

# Step 4: Adjust to the default keyboard shortcuts changes

# Ctrl vs Cmd

# Keyboard shortcuts changes: Navigation

# Keyboard shortcuts changes: Selection

# Keyboard shortcuts changes: Edition

# Keyboard shortcuts changes: Cell merging

# Migrating to Handsontable 12.0

# Step 5: Avoid referring to _wt

# Migrating to Handsontable 12.0

# Step 1: Verify your `updateSettings()` calls

# Step 2: Adjust to the `updatePlugin()` changes

# Step 3: Adjust to the `afterDocumentKeyDown` changes

# `Ctrl` vs `Cmd`

# Step 5: Avoid referring to `_wt`