Custom plugins

Extend Handsontable’s functionality by writing your custom plugin. Use the BasePlugin for a quick start.

Overview

Plugins are a great way of extending Handsontable’s capabilities. In fact, most Handsontable features are provided by plugins.

Reach for a custom plugin when you need to share state across multiple hooks. A plugin also fits when you need an enable, disable, or update lifecycle, or a reusable, registrable unit for other developers to use. If you only need to react to a single action, add a hook instead - see Events and hooks.

Prerequisites

Import the following:
- BasePlugin - a built-in interface that lets you work within Handsontable’s lifecycle,
- registerPlugin - a utility to register a plugin in the Handsontable plugin registry.
In TypeScript, also import HotInstance, CellChange, and ChangeSource.
JavaScript
```
1
import { BasePlugin, registerPlugin } from 'handsontable/plugins';
```
TypeScript
```
1
import { BasePlugin, registerPlugin } from 'handsontable/plugins';
2
import type { CellChange, ChangeSource, HotInstance } from 'handsontable';
```

Extend the `BasePlugin`

The best way to start creating your own plugin is to extend the BasePlugin.

The BasePlugin interface takes care of:

Backward compatibility
Memory leak prevention
Properly binding your plugin’s instance to Handsontable

Declare configuration on the class in the TypeScript example. disablePlugin() sets that field to null, so the afterChange log reads configuration?.msg.

1
export class CustomPlugin extends BasePlugin {
2
 /**
3
  * Define a unique key (a string) for your plugin.
4
  * The key becomes the plugin's alias.
5
  * Handsontable registers the plugin under that alias.
6
  * When an `updateSettings()` call includes the plugin's alias,
7
  * your plugin's state gets updated.
8
  * You can also use the alias to recognize the plugin's
9
  * options passed through the Setting object at Handsontable's initialization.
10
  *
11
  * @returns {string}
12
  */
13
  static get PLUGIN_KEY() {
14
    return 'customPlugin';
15
  }
16

17
 /**
18
  * Define additional setting keys (an array of strings) for your plugin.
19
  * When an `updateSettings()` call includes at least one of those setting keys,
20
  * your plugin's state gets updated.
21
  * If you set SETTING_KEYS() to return `true`, your plugin updates on every `updateSettings()` call.
22
  * If you set SETTING_KEYS() to return `false`, your plugin never updates on any `updateSettings()` call.
23
  *
24
  * @returns {Array|boolean}
25
  */
26
  static get SETTING_KEYS() {
27
    return true;
28
  }
29

30
  /**
31
   * Extend the default constructor and define internal properties for your plugin.
32
   *
33
   * @param {Handsontable} hotInstance
34
   */
35
  constructor(hotInstance) {
36
     /**
37
     * The [`BasePlugin`](/docs/javascript-data-grid/api/base-plugin/)'s constructor adds a `this.hot` property to your plugin.
38
     * The `this.hot` property:
39
     * - Is a reference to the Handsontable instance.
40
     * - Can't be overwritten.
41
     * - Gives you access to columns' and rows' index mappers.
42
     */
43
    super(hotInstance);
44

45
    // Initialize all your public properties in the class'
46
    // constructor.
47
    this.configuration = {
48
      enabled: false,
49
      msg: ''
50
    };
51
  }
52

53
  /**
54
   * Unifies configuration passed to settings object.
55
   *
56
   * @returns {object}
57
   * @throws {Error}
58
   */
59
  getUnifiedConfig() {
60
    const pluginSettings = this.hot.getSettings()[CustomPlugin.PLUGIN_KEY];
61

62
    if (pluginSettings === true) {
63
      return {
64
        enabled: true,
65
        msg: 'default msg boolean'
66
      };
67
    }
68
    if (Object.prototype.toString.call(pluginSettings) === '[object Object]') {
69
      return {
70
        enabled: true,
71
        msg: 'default msg obj',
72
        ...pluginSettings
73
      };
74
    }
75
    if (pluginSettings === false) {
76
      return {
77
        enabled: false,
78
        msg: ''
79
      };
80
    }
81

82
    throw new Error(
83
      `${CustomPlugin.PLUGIN_KEY} - incorrect plugins configuration.
84
      Passed:
85
        - type: ${typeof pluginSettings}
86
        - value: ${JSON.stringify(pluginSettings, null, ' ')}
87

88
      Expected:
89
        - boolean
90
        - object
91
      `
92
    );
93
  }
94

95
  /**
96
   * Checks if the plugin is enabled in the settings.
97
   */
98
  isEnabled() {
99
    const pluginSettings = this.getUnifiedConfig();
100

101
    return pluginSettings.enabled;
102
  }
103

104
  /**
105
   * The `enablePlugin` method is triggered on the `beforeInit` hook.
106
   * It should contain your plugin's initial setup and hook connections.
107
   * This method is run only if the `isEnabled` method returns `true`.
108
   */
109
  enablePlugin() {
110
    // Get the plugin's configuration from the initialization object.
111
    this.configuration = this.getUnifiedConfig();
112

113
    // Add all your plugin hooks here. It's a good idea to use arrow
114
    // functions to keep the plugin as a context.
115
    this.addHook('afterChange', (changes, source) => this.onAfterChange(changes, source));
116

117
    // The `super` method sets the `this.enabled` property to `true`.
118
    // It is a necessary step to update the plugin's settings
119
    // properly.
120
    super.enablePlugin();
121
  }
122

123
  /**
124
   * The `disablePlugin` method disables the plugin.
125
   */
126
  disablePlugin() {
127
    // Reset all of your plugin class properties to their default
128
    // values here.
129
    this.configuration = null;
130

131
    // The `BasePlugin.disablePlugin` method takes care of clearing
132
    // the hook connections
133
    // and assigning the 'false' value to the 'this.enabled' property.
134
    super.disablePlugin();
135
  }
136

137
  /**
138
   * The `updatePlugin` method is called on the `afterUpdateSettings` hook
139
   * (unless the `updateSettings` method turned the plugin off),
140
   * but only if the config object passed to the `updateSettings` method
141
   * contains entries relevant to that particular plugin.
142
   *
143
   * The `updatePlugin` method should contain anything that your plugin needs to do to work correctly
144
   * after updating the Handsontable instance settings.
145
   */
146
  updatePlugin() {
147
    // The `updatePlugin` method needs to contain all the code needed
148
    // to properly re-enable the plugin.
149
    // In most cases, disabling and enabling the plugin should
150
    // do the trick.
151
    const { enabled, msg } = this.getUnifiedConfig();
152

153
    // You can decide if updating the settings triggers the
154
    // disable->enable routine or not.
155
    if (enabled === false && this.enabled === true) {
156
      this.disablePlugin();
157
    } else if (enabled === true && this.enabled === false) {
158
      this.enablePlugin();
159
    }
160

161
    // If you need to update just a single option.
162
    if (this.configuration !== null && msg && this.configuration.msg !== msg) {
163
      this.configuration.msg = msg;
164
    }
165

166
    super.updatePlugin();
167
  }
168

169
  /**
170
   * Define your external methods.
171
   */
172
  externalMethodExample() {
173
    // Method definition.
174
  }
175

176
  /**
177
   * The afterChange hook callback.
178
   *
179
   * @param {CellChange[]} changes An array of changes.
180
   * @param {string} source Describes the source of the change.
181
   */
182
  onAfterChange(changes, source) {
183
    // afterChange callback goes here.
184
    console.log(
185
      `${CustomPlugin.PLUGIN_KEY}.onAfterChange - ${this.configuration.msg}`,
186
      changes,
187
      source
188
    );
189
  }
190

191
  /**
192
   * The `destroy` method is the best place to clean up any instances,
193
   * objects or index mappers created during the plugin's lifecycle.
194
   */
195
  destroy() {
196
    // The `super` method cleans up the plugin's event callbacks, hook
197
    // connections, and properties.
198
    super.destroy();
199
  }
200
}

1
type CustomPluginConfig = {
2
  enabled: boolean;
3
  msg: string;
4
};
5

6
export class CustomPlugin extends BasePlugin {
7
  configuration: CustomPluginConfig | null;
8

9
 /**
10
  * Define a unique key (a string) for your plugin.
11
  * The key becomes the plugin's alias.
12
  * Handsontable registers the plugin under that alias.
13
  * When an `updateSettings()` call includes the plugin's alias,
14
  * your plugin's state gets updated.
15
  * You can also use the alias to recognize the plugin's
16
  * options passed through the Setting object at Handsontable's initialization.
17
  *
18
  * @returns The plugin alias.
19
  */
20
  static get PLUGIN_KEY() {
21
    return 'customPlugin';
22
  }
23

24
 /**
25
  * Define additional setting keys (an array of strings) for your plugin.
26
  * When an `updateSettings()` call includes at least one of those setting keys,
27
  * your plugin's state gets updated.
28
  * If you set SETTING_KEYS() to return `true`, your plugin updates on every `updateSettings()` call.
29
  * If you set SETTING_KEYS() to return `false`, your plugin never updates on any `updateSettings()` call.
30
  *
31
  * @returns The setting keys, or a boolean.
32
  */
33
  static get SETTING_KEYS() {
34
    return true;
35
  }
36

37
  /**
38
   * Extend the default constructor and define internal properties for your plugin.
39
   *
40
   * @param hotInstance The Handsontable instance.
41
   */
42
  constructor(hotInstance: HotInstance) {
43
     /**
44
     * The [`BasePlugin`](/docs/javascript-data-grid/api/base-plugin/)'s constructor adds a `this.hot` property to your plugin.
45
     * The `this.hot` property:
46
     * - Is a reference to the Handsontable instance.
47
     * - Can't be overwritten.
48
     * - Gives you access to columns' and rows' index mappers.
49
     */
50
    super(hotInstance);
51

52
    // Initialize all your public properties in the class'
53
    // constructor.
54
    this.configuration = {
55
      enabled: false,
56
      msg: ''
57
    };
58
  }
59

60
  /**
61
   * Unifies configuration passed to settings object.
62
   *
63
   * @returns The plugin options.
64
   * @throws {Error}
65
   */
66
  getUnifiedConfig(): CustomPluginConfig {
67
    const pluginSettings = this.hot.getSettings()[CustomPlugin.PLUGIN_KEY];
68

69
    if (pluginSettings === true) {
70
      return {
71
        enabled: true,
72
        msg: 'default msg boolean'
73
      };
74
    }
75
    if (Object.prototype.toString.call(pluginSettings) === '[object Object]') {
76
      return {
77
        enabled: true,
78
        msg: 'default msg obj',
79
        ...pluginSettings
80
      };
81
    }
82
    if (pluginSettings === false) {
83
      return {
84
        enabled: false,
85
        msg: ''
86
      };
87
    }
88

89
    throw new Error(
90
      `${CustomPlugin.PLUGIN_KEY} - incorrect plugins configuration.
91
      Passed:
92
        - type: ${typeof pluginSettings}
93
        - value: ${JSON.stringify(pluginSettings, null, ' ')}
94

95
      Expected:
96
        - boolean
97
        - object
98
      `
99
    );
100
  }
101

102
  /**
103
   * Checks if the plugin is enabled in the settings.
104
   */
105
  isEnabled() {
106
    const pluginSettings = this.getUnifiedConfig();
107

108
    return pluginSettings.enabled;
109
  }
110

111
  /**
112
   * The `enablePlugin` method is triggered on the `beforeInit` hook.
113
   * It should contain your plugin's initial setup and hook connections.
114
   * This method is run only if the `isEnabled` method returns `true`.
115
   */
116
  enablePlugin() {
117
    // Get the plugin's configuration from the initialization object.
118
    this.configuration = this.getUnifiedConfig();
119

120
    // Add all your plugin hooks here. It's a good idea to use arrow
121
    // functions to keep the plugin as a context.
122
    this.addHook('afterChange', (changes, source) => this.onAfterChange(changes, source));
123

124
    // The `super` method sets the `this.enabled` property to `true`.
125
    // It is a necessary step to update the plugin's settings
126
    // properly.
127
    super.enablePlugin();
128
  }
129

130
  /**
131
   * The `disablePlugin` method disables the plugin.
132
   */
133
  disablePlugin() {
134
    // Reset all of your plugin class properties to their default
135
    // values here.
136
    this.configuration = null;
137

138
    // The `BasePlugin.disablePlugin` method takes care of clearing
139
    // the hook connections
140
    // and assigning the 'false' value to the 'this.enabled' property.
141
    super.disablePlugin();
142
  }
143

144
  /**
145
   * The `updatePlugin` method is called on the `afterUpdateSettings` hook
146
   * (unless the `updateSettings` method turned the plugin off),
147
   * but only if the config object passed to the `updateSettings` method
148
   * contains entries relevant to that particular plugin.
149
   *
150
   * The `updatePlugin` method should contain anything that your plugin needs to do to work correctly
151
   * after updating the Handsontable instance settings.
152
   */
153
  updatePlugin() {
154
    // The `updatePlugin` method needs to contain all the code needed
155
    // to properly re-enable the plugin.
156
    // In most cases, disabling and enabling the plugin should
157
    // do the trick.
158
    const { enabled, msg } = this.getUnifiedConfig();
159

160
    // You can decide if updating the settings triggers the
161
    // disable->enable routine or not.
162
    if (enabled === false && this.enabled === true) {
163
      this.disablePlugin();
164
    } else if (enabled === true && this.enabled === false) {
165
      this.enablePlugin();
166
    }
167

168
    // If you need to update just a single option.
169
    if (this.configuration !== null && msg && this.configuration.msg !== msg) {
170
      this.configuration.msg = msg;
171
    }
172

173
    super.updatePlugin();
174
  }
175

176
  /**
177
   * Define your external methods.
178
   */
179
  externalMethodExample() {
180
    // Method definition.
181
  }
182

183
  /**
184
   * The afterChange hook callback.
185
   *
186
   * @param changes An array of changes, or `null`.
187
   * @param source Describes the source of the change.
188
   */
189
  onAfterChange(changes: CellChange[] | null, source: ChangeSource): void {
190
    // afterChange callback goes here.
191
    console.log(
192
      `${CustomPlugin.PLUGIN_KEY}.onAfterChange - ${this.configuration?.msg}`,
193
      changes,
194
      source
195
    );
196
  }
197

198
  /**
199
   * The `destroy` method is the best place to clean up any instances,
200
   * objects or index mappers created during the plugin's lifecycle.
201
   */
202
  destroy() {
203
    // The `super` method cleans up the plugin's event callbacks, hook
204
    // connections, and properties.
205
    super.destroy();
206
  }
207
}

Register CustomPlugin

Now, register your plugin.

There are two ways to register a plugin:
- Option 1: Define a static getter named PLUGIN_KEY that the registerPlugin utility uses as the plugin’s alias. Check the example in the code snippet above.
```
1
// You need to register your plugin in order to use it within
2
// Handsontable.
3
registerPlugin(CustomPlugin);
```
- Option 2: Use a custom alias. Put a string in the first argument. The registerer uses that string as an alias, instead of the PLUGIN_KEY getter from CustomPlugin.
```
1
registerPlugin('CustomAlias', CustomPlugin);
```

Use your plugin in Handsontable

To control the plugin’s options, pass a boolean or an object at the plugin’s initialization:

1
import Handsontable from 'handsontable';
2
import { CustomPlugin } from './customPlugin';
3

4
const hotInstance = new Handsontable(container, {
5
  // Pass `true` to enable the plugin with default options.
6
  [CustomPlugin.PLUGIN_KEY]: true,
7
  // You can also enable the plugin by passing an object with options.
8
  [CustomPlugin.PLUGIN_KEY]: {
9
    msg: 'user-defined message',
10
  },
11
  // You can also initialize the plugin without enabling it at the
12
  // beginning.
13
  [CustomPlugin.PLUGIN_KEY]: false,
14
});

Get a reference to the plugin’s instance

To use the plugin’s API, call the getPlugin method to get a reference to the plugin’s instance.

getPlugin() returns BasePlugin, so cast the result to your plugin class to call its methods.

1
const pluginInstance = hotInstance.getPlugin(CustomPlugin.PLUGIN_KEY);
2

3
pluginInstance.externalMethodExample();

1
const pluginInstance = hotInstance.getPlugin(CustomPlugin.PLUGIN_KEY) as CustomPlugin;
2

3
pluginInstance.externalMethodExample();

APIs:

BasePlugin

Core methods:

getPlugin()

Hooks:

afterPluginsInitialized

Custom plugins

Overview

Prerequisites

Extend the BasePlugin

Register CustomPlugin

Use your plugin in Handsontable

Get a reference to the plugin’s instance

Related API reference

Extend the `BasePlugin`