Skip to content

Row moving

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

Enable the ManualRowMove plugin

To enable row moving, set the manualRowMove option to true.

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

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

JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const data = [
['SKU-4821', 'Stainless Steel Water Bottle', 'Harbor Goods', 'Drinkware', 'Seattle'],
['SKU-0093', 'Wireless Mouse', 'Alpine Supply Co.', 'Electronics', 'Denver'],
['SKU-1170', 'Ergonomic Office Chair', 'Cascade Distributors', 'Furniture', 'Portland'],
['SKU-2208', 'USB-C Charging Cable', 'Summit Trading', 'Electronics', 'Austin'],
['SKU-3341', 'Aluminum Water Filter', 'Northgate Wholesale', 'Drinkware', 'Minneapolis'],
['SKU-4412', 'Canvas Tote Bag', 'Nordic Traders', 'Apparel', 'Boston'],
['SKU-5088', 'USB-C Hub', 'Harbor Goods', 'Electronics', 'Chicago'],
['SKU-6120', 'Ceramic Mug Set', 'Alpine Supply Co.', 'Drinkware', 'Phoenix'],
['SKU-7294', 'Desk Lamp', 'Cascade Distributors', 'Furniture', 'Atlanta'],
['SKU-8015', 'Laptop Stand', 'Summit Trading', 'Furniture', 'Dallas'],
['SKU-9166', 'Bluetooth Speaker', 'Northgate Wholesale', 'Electronics', 'San Jose'],
['SKU-1042', 'Standing Desk', 'Nordic Traders', 'Furniture', 'Columbus'],
];
const container = document.querySelector('#example1');
new Handsontable(container, {
data,
width: '100%',
height: 320,
rowHeaders: true,
colHeaders: true,
colWidths: 100,
manualRowMove: 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();
const data: string[][] = [
['SKU-4821', 'Stainless Steel Water Bottle', 'Harbor Goods', 'Drinkware', 'Seattle'],
['SKU-0093', 'Wireless Mouse', 'Alpine Supply Co.', 'Electronics', 'Denver'],
['SKU-1170', 'Ergonomic Office Chair', 'Cascade Distributors', 'Furniture', 'Portland'],
['SKU-2208', 'USB-C Charging Cable', 'Summit Trading', 'Electronics', 'Austin'],
['SKU-3341', 'Aluminum Water Filter', 'Northgate Wholesale', 'Drinkware', 'Minneapolis'],
['SKU-4412', 'Canvas Tote Bag', 'Nordic Traders', 'Apparel', 'Boston'],
['SKU-5088', 'USB-C Hub', 'Harbor Goods', 'Electronics', 'Chicago'],
['SKU-6120', 'Ceramic Mug Set', 'Alpine Supply Co.', 'Drinkware', 'Phoenix'],
['SKU-7294', 'Desk Lamp', 'Cascade Distributors', 'Furniture', 'Atlanta'],
['SKU-8015', 'Laptop Stand', 'Summit Trading', 'Furniture', 'Dallas'],
['SKU-9166', 'Bluetooth Speaker', 'Northgate Wholesale', 'Electronics', 'San Jose'],
['SKU-1042', 'Standing Desk', 'Nordic Traders', 'Furniture', 'Columbus'],
];
const container = document.querySelector('#example1')!;
new Handsontable(container, {
data,
width: '100%',
height: 320,
rowHeaders: true,
colHeaders: true,
colWidths: 100,
manualRowMove: true,
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});

Set a pre-defined row order

Instead of setting manualRowMove to true, you can pass an array of physical row indexes to define the initial visual order of rows on render.

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

manualRowMove: [2, 0, 1]

This renders the rows in the following order:

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

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

Data model behavior

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

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

To save the new order after a move, listen to the afterRowMove hook:

afterRowMove(movedRows, finalIndex, dropIndex, movePossible, orderChanged) {
if (orderChanged) {
const reorderedData = this.getData();
// persist reorderedData to your backend
}
}

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 row order on purpose, so Handsontable re-applies the order map it already holds on top of your already-reordered array. One drag then moves the row twice.

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

To replace the data and reset the order together, call loadData() instead. It clears the row order map along with the data, and it clears the undo history.

One exception: if you passed manualRowMove as an array of indexes, the plugin re-applies that array right after the reset. You get the configured order back, not the source order.

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

Result

After completing this guide, you can reorder rows by dragging them with the mouse or by calling dragRows() and moveRows() programmatically. You can also set a pre-defined row order at initialization.

API reference

dragRows vs moveRows

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

Both of these methods trigger the beforeRowMove and afterRowMove hooks, but only dragRows passes the dropIndex argument to them.

Pressing a row header with the mouse and releasing it without moving the pointer more than a few pixels is the exception. That click moves nothing, and neither hook fires. Calling moveRows or dragRows from your code always fires both hooks.

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

dragRows method

The moveRows 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.

moveRows method

The moveRows 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 beforeRowMove and afterRowMove hooks help in determine such situations.

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

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

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

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

When some rows are hidden, a row that a user drags into the gap between the visible rows around them lands after the hidden rows, right before the next visible row. The gap has two drop positions, the lower half of the row above the hidden rows and the upper half of the row below them, and both give the same order of all rows. A row dropped on its own lower half stays where it is, so for the row right above the hidden rows the two halves of the gap differ: its own lower half changes nothing, and the upper half of the row below moves it after the hidden rows. If the hidden rows are the last rows of the grid, the row lands in front of them. The row also stays in front of the hidden rows when landing after them would cross the edge of the fixed rows at the top or at the bottom, when it would split a merged cell, and when the NestedRows plugin is enabled. The dragRows() and dragRow() methods use the drop index you pass: a drop index that points at the first hidden row of a block puts the row in front of the block, and one that points at another hidden row of the block puts the row between the hidden rows.

The moveRows method is also inactive when the NestedRows plugin is enabled - see Row parent-child known limitations.

Configuration options

Core methods

Hooks

Plugins