Adding and removing columns

Insert and remove columns programmatically with the alter() method, through the context menu, or automatically with spare columns.

Insert and remove columns with the API

Call the alter() method to change the column structure programmatically. Pass an action name, a column index, and the number of columns to insert or remove:

alter('insert_col_start', index, amount) inserts columns to the left of the given column index.
alter('insert_col_end', index, amount) inserts columns to the right of the given column index.
alter('remove_col', index, amount) removes columns, starting at the given column index.

In the example below, Insert column appends a column to the right of the last column, and Remove last column removes the last column.

1
<script setup lang="ts">
2
import { ref, useTemplateRef } from 'vue';
3
import { HotTable } from '@handsontable/vue3';
4
import { registerAllModules } from 'handsontable/registry';
5
import type { GridSettings } from 'handsontable/settings';
6

7
// register Handsontable's modules
8
registerAllModules();
9

10
const hotRef = useTemplateRef<InstanceType<typeof HotTable>>('hotRef');
11

12
const hotSettings = ref<GridSettings>({
13
  data: [
14
    ['Ana García', 'Engineering', 'Senior Engineer', '2021-04-12'],
15
    ['James Okafor', 'Marketing', 'Product Manager', '2022-08-30'],
16
    ['Li Wei', 'Engineering', 'Staff Engineer', '2019-02-18'],
17
    ['Sofia Rossi', 'Sales', 'Account Executive', '2023-01-09'],
18
    ['Diego Fernández', 'Design', 'UX Designer', '2020-11-23'],
19
    ['Amara Singh', 'Engineering', 'Engineering Manager', '2018-06-05'],
20
  ],
21
  colHeaders: ['Name', 'Department', 'Title', 'Hire date'],
22
  rowHeaders: true,
23
  height: 'auto',
24
  autoWrapRow: true,
25
  autoWrapCol: true,
26
  licenseKey: 'non-commercial-and-evaluation',
27
});
28

29
function insertColumn() {
30
  const hot = hotRef.value?.hotInstance;
31

32
  // insert one column at the end of the grid
33
  hot?.alter('insert_col_end', hot.countCols() - 1, 1);
34
}
35

36
function removeColumn() {
37
  const hot = hotRef.value?.hotInstance;
38

39
  // remove the last column, but keep at least one column in the grid
40
  if (hot && hot.countCols() > 1) {
41
    hot.alter('remove_col', hot.countCols() - 1, 1);
42
  }
43
}
44
</script>
45

46
<template>
47
  <div id="example1">
48
    <div class="example-controls-container">
49
      <div class="controls">
50
        <button class="button button--primary" @click="insertColumn">
51
          Insert column
52
        </button>
53
        <button class="button button--primary" @click="removeColumn">
54
          Remove last column
55
        </button>
56
      </div>
57
    </div>
58
    <HotTable ref="hotRef" :settings="hotSettings" />
59
  </div>
60
</template>

The index argument uses visual column indexes. The amount argument defaults to 1 when omitted.

Enable the contextMenu option to let users insert and remove columns by right-clicking a column. The relevant menu items are col_left (Insert column left), col_right (Insert column right), and remove_col (Remove column).

Setting contextMenu to true shows the full default menu. To show only the column actions, pass an array of item keys, as in the example below. Right-click a column header or cell to open the menu.

1
<script setup lang="ts">
2
import { ref } from 'vue';
3
import { HotTable } from '@handsontable/vue3';
4
import { registerAllModules } from 'handsontable/registry';
5
import type { GridSettings } from 'handsontable/settings';
6

7
// register Handsontable's modules
8
registerAllModules();
9

10
const hotSettings = ref<GridSettings>({
11
  data: [
12
    ['Ana García', 'Engineering', 'Senior Engineer', '2021-04-12'],
13
    ['James Okafor', 'Marketing', 'Product Manager', '2022-08-30'],
14
    ['Li Wei', 'Engineering', 'Staff Engineer', '2019-02-18'],
15
    ['Sofia Rossi', 'Sales', 'Account Executive', '2023-01-09'],
16
    ['Diego Fernández', 'Design', 'UX Designer', '2020-11-23'],
17
    ['Amara Singh', 'Engineering', 'Engineering Manager', '2018-06-05'],
18
  ],
19
  colHeaders: ['Name', 'Department', 'Title', 'Hire date'],
20
  rowHeaders: true,
21
  height: 'auto',
22
  // show only the column insert and remove items in the context menu
23
  contextMenu: ['col_left', 'col_right', 'remove_col'],
24
  autoWrapRow: true,
25
  autoWrapCol: true,
26
  licenseKey: 'non-commercial-and-evaluation',
27
});
28
</script>
29

30
<template>
31
  <div id="example2">
32
    <HotTable :settings="hotSettings" />
33
  </div>
34
</template>

The allowInsertColumn and allowRemoveColumn options control whether these context menu items are available. Both default to true. Set allowInsertColumn to false to hide the insert items, or allowRemoveColumn to false to hide the remove item.

Add spare columns automatically

Set the minSpareCols option to keep a number of empty columns at the end of the grid. When a user enters data in the last empty column, Handsontable adds another empty column, so the grid always has at least the configured number of spare columns.

1
const configurationOptions = {
2
  // keep at least one empty column at the end of the grid
3
  minSpareCols: 1,
4
};

minSpareCols defaults to 0.

Control and react to column changes

Use Handsontable’s hooks to validate or respond to column changes:

beforeCreateCol runs before columns are inserted. Return false to cancel the insertion.
afterCreateCol runs after columns are inserted.
beforeRemoveCol runs before columns are removed. Return false to cancel the removal.
afterRemoveCol runs after columns are removed.

For example, block removing the last remaining column:

1
const configurationOptions = {
2
  beforeRemoveCol(index, amount) {
3
    if (this.countCols() - amount < 1) {
4
      // cancel the removal
5
      return false;
6
    }
7
  },
8
};

Result

After completing this guide, you can insert and remove columns with the alter() method, let users add and remove columns through the context menu, keep spare columns at the end of the grid, and validate or react to column changes with hooks.

Configuration options

Core methods

Hooks