Skip to content

Column moving

Change the order of columns, either manually (dragging them to another location), or programmatically (using Handsontable DataGrid’s API methods).

Enable the plugin

To enable column moving, set the manualColumnMove configuration option to true.

A draggable move handle appears above the selected column header. You can click and drag it to any location in the grid.

You can drag one range of columns at a time. When the selection holds several ranges (made with Ctrl/Cmd+click), a drag on a header moves nothing.

A column has to be selected before you can drag it. You can start the drag anywhere on the selected column’s header, including on the sorting label when column sorting is enabled. Handsontable tells a click from a drag by whether the pointer moves: press and release without moving to sort the column, and press and drag to move it.

When column sorting is enabled, only the header label and its sort indicator sort on click. Pressing the header around them selects the column without sorting it, so you can select a column and drag it in one gesture.

JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
// generate an array of arrays with dummy data
const data = new Array(200) // number of rows
.fill(null)
.map((_, row) =>
new Array(20) // number of columns
.fill(null)
.map((_, column) => `${row}, ${column}`)
);
const container = document.querySelector('#example1');
new Handsontable(container, {
data,
width: '100%',
height: 320,
rowHeaders: true,
colHeaders: true,
colWidths: 100,
manualColumnMove: true,
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
TypeScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
// generate an array of arrays with dummy data
const data: string[][] = new Array(200) // number of rows
.fill(null)
.map((_, row) =>
new Array(20) // number of columns
.fill(null)
.map((_, column) => `${row}, ${column}`)
);
const container = document.querySelector('#example1')!;
new Handsontable(container, {
data,
width: '100%',
height: 320,
rowHeaders: true,
colHeaders: true,
colWidths: 100,
manualColumnMove: true,
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});

Move column headers

When you move columns, the default column headers (A, B, C) stay in place.

JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example2');
new Handsontable(container, {
data: [
['SKU-4821', 'Stainless Steel Water Bottle', 'Harbor Goods'],
['SKU-0093', 'Wireless Mouse', 'Alpine Supply Co.'],
['SKU-1170', 'Ergonomic Office Chair', 'Cascade Distributors'],
],
colHeaders: true,
rowHeaders: true,
manualColumnMove: true,
autoWrapRow: true,
autoWrapCol: true,
height: 'auto',
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
TypeScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example2')!;
new Handsontable(container, {
data: [
['SKU-4821', 'Stainless Steel Water Bottle', 'Harbor Goods'],
['SKU-0093', 'Wireless Mouse', 'Alpine Supply Co.'],
['SKU-1170', 'Ergonomic Office Chair', 'Cascade Distributors'],
],
colHeaders: true,
rowHeaders: true,
manualColumnMove: true,
autoWrapRow: true,
autoWrapCol: true,
height: 'auto',
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});

But, if you configure the colHeaders option with your own column labels (e.g., SKU, Product, Supplier), your headers move along with the columns.

JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example3');
new Handsontable(container, {
data: [
['SKU-4821', 'Stainless Steel Water Bottle', 'Harbor Goods'],
['SKU-0093', 'Wireless Mouse', 'Alpine Supply Co.'],
['SKU-1170', 'Ergonomic Office Chair', 'Cascade Distributors'],
],
colHeaders: ['SKU', 'Product', 'Supplier'],
rowHeaders: true,
manualColumnMove: true,
autoWrapRow: true,
autoWrapCol: true,
height: 'auto',
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
TypeScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example3')!;
new Handsontable(container, {
data: [
['SKU-4821', 'Stainless Steel Water Bottle', 'Harbor Goods'],
['SKU-0093', 'Wireless Mouse', 'Alpine Supply Co.'],
['SKU-1170', 'Ergonomic Office Chair', 'Cascade Distributors'],
],
colHeaders: ['SKU', 'Product', 'Supplier'],
rowHeaders: true,
manualColumnMove: true,
autoWrapRow: true,
autoWrapCol: true,
height: 'auto',
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});

Set a pre-defined column order

Instead of setting manualColumnMove to true, you can pass an array of physical column indexes to define the initial visual order of columns on render.

Each position in the array corresponds to a visual (display) position, and the value at that position is the physical (source data) column index. For example:

manualColumnMove: [1, 0, 2]

This renders the columns in the following order:

  • Visual position 0 → physical column 1
  • Visual position 1 → physical column 0
  • Visual position 2 → physical column 2

The array must contain all physical column indexes (its length must equal the total number of columns). After the initial render, users can still drag columns to change the order further.

For more on how physical and visual indexes relate, see Understanding data and indexes.

Data model behavior

Moving columns does not reorder your source data. Handsontable stores the new order as index metadata through its IndexMapper, and leaves the original data untouched. This affects how you read and save the data:

  • getData() returns cells in their current visual order, so it reflects any moves. Call it inside the afterColumnMove hook to get an order-accurate snapshot to persist.
  • getSourceData() returns cells in their original physical order, ignoring any moves.

Don’t feed the snapshot back into the grid

Sending the reordered snapshot back to the grid as its new data applies the move a second time. updateData() keeps the current column order on purpose, so Handsontable re-applies the order map it already holds on top of your already-reordered data. One drag then moves the column twice.

Treat the snapshot as output only. Send it to your backend, and leave the grid’s own data alone.

Control column moving

Use the beforeColumnMove hook to decide whether each column move is allowed. Returning false cancels the move while keeping the manualColumnMove plugin enabled.

Both beforeColumnMove and afterColumnMove run only when the pointer actually drags a column. A click on a column header does not fire them.

In the following example, select Allow column moving before you drag a column to a new position. Clear the checkbox to block column moving again.

JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
registerAllModules();
const data = [
['SKU-4821', 'Wireless keyboard', 'Harbor Goods', 142],
['SKU-0093', 'USB-C dock', 'Vertex Supply', 67],
['SKU-3148', '27-inch monitor', 'Alpine Supply Co.', 24],
['SKU-7720', 'Laptop stand', 'Northstar Wholesale', 89],
['SKU-1056', 'Noise-canceling headset', 'Summit Distribution', 35],
];
const container = document.querySelector('#example4');
const allowColumnMovingInput = document.querySelector('#allow-column-moving');
let allowColumnMoving = false;
allowColumnMovingInput.addEventListener('change', () => {
allowColumnMoving = allowColumnMovingInput.checked;
});
new Handsontable(container, {
data,
colHeaders: ['SKU', 'Product', 'Supplier', 'Stock'],
rowHeaders: true,
manualColumnMove: true,
beforeColumnMove: () => allowColumnMoving,
stretchH: 'all',
height: 'auto',
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
TypeScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
registerAllModules();
const data = [
['SKU-4821', 'Wireless keyboard', 'Harbor Goods', 142],
['SKU-0093', 'USB-C dock', 'Vertex Supply', 67],
['SKU-3148', '27-inch monitor', 'Alpine Supply Co.', 24],
['SKU-7720', 'Laptop stand', 'Northstar Wholesale', 89],
['SKU-1056', 'Noise-canceling headset', 'Summit Distribution', 35],
];
const container = document.querySelector('#example4')!;
const allowColumnMovingInput = document.querySelector<HTMLInputElement>('#allow-column-moving')!;
let allowColumnMoving = false;
allowColumnMovingInput.addEventListener('change', () => {
allowColumnMoving = allowColumnMovingInput.checked;
});
new Handsontable(container, {
data,
colHeaders: ['SKU', 'Product', 'Supplier', 'Stock'],
rowHeaders: true,
manualColumnMove: true,
beforeColumnMove: () => allowColumnMoving,
stretchH: 'all',
height: 'auto',
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
HTML
<div class="example-controls-container">
<div class="controls">
<label>
<input id="allow-column-moving" type="checkbox" />
Allow column moving
</label>
</div>
</div>
<div id="example4"></div>

Result

After completing this guide, you can reorder columns by dragging them with the mouse or by calling dragColumns() and moveColumns() programmatically. You can also set a pre-defined column order at initialization or use beforeColumnMove to block individual moves.

Drag and move actions of the ManualColumnMove plugin

There are significant differences between the plugin’s dragColumns and moveColumns API functions. Both of them change the order of columns, but they rely on different kinds of indexes. The differences between them are shown in the diagrams below.

Both of these methods trigger the beforeColumnMove and afterColumnMove hooks, but only dragColumns passes the dropIndex argument to them.

The dragColumns method has a dropIndex parameter, which points to where the elements are being dropped.

dragColumns method

The moveColumns method has a finalIndex parameter, which points to where the elements will be placed after the moving action - finalIndex being the index of the first moved element.

moveColumns method

The moveColumns function cannot perform some actions, e.g., more than one element can’t be moved to the last position. In this scenario, the move will be canceled. The Plugin’s isMovePossible API method and the movePossible parameters beforeColumnMove and afterColumnMove hooks help in determine such situations.

The beforeColumnMove and afterColumnMove hooks also fire when a move leaves the order unchanged, for example when you grab a column header and drop the column back where it was. In that case, movePossible is true and the orderChanged parameter of afterColumnMove is false. Check orderChanged to ignore such moves. The order of the columns stays as it was, even when some columns are trimmed.

When some columns are trimmed, a moved column lands next to the visible column at the drop position. It never splits a run of neighboring trimmed columns:

  • Moved to a position before a visible column, it lands right before that column, after any trimmed columns that sit in front of it.
  • Moved to the last visible position, it lands right after the last visible column, before any trimmed columns at the end.

You see where the column landed when you untrim the columns. For example, in a grid of six columns where the last two columns are trimmed, moving the first column to the last visible position leaves it in front of the two trimmed columns.

Configuration options

Core methods

Hooks

Plugins