Migrating from 11.1 to 12.0

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

More information about this release can be found in the 12.0.0 release blog post.
For a detailed list of changes in this release, see the Changelog.

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:

   • Referencing the Handsontable instance in Angular
   • Referencing the Handsontable instance in React
   • Referencing the Handsontable instance in Vue
   • Referencing the Handsontable instance in Vue 3

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.

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:

   • Context menu
   • Dropdown menu

   Migrating to Handsontable 12.0

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

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:

   • Add a custom keyboard shortcut
   • Remove a default keyboard shortcut
   • Replace a default keyboard shortcut
   • Block a default keyboard shortcut’s action

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.