Row order
Reorder rows by dragging a marker handle, with keyboard shortcuts, or from code, and read the move operations that the grid reports.
Some lists have a meaning in their order, such as a playlist or a priority queue. Users drag the handle in the row marker column to move a row. A thin line marks the drop target, and the row moves on release. Keyboard shortcuts and reorderRows do the same without a pointer.
move operations show up here.Enable reordering
Set rowMarkers to a mode of the reorder family: "reorder", "reorder-number", "reorder-checkbox", or "reorder-both". The other marker modes have no handle. This grid uses "reorder-checkbox":
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
type Row = { id: string; title: string };
const columns = defineColumns<Row>()([
{ id: "title", header: "Title", accessorKey: "title" },
]);
const rows: Row[] = [
{ id: "1", title: "Intro" },
{ id: "2", title: "Verse" },
];
function Playlist() {
return (
<DataGrid
defaultData={rows}
columns={columns}
rowMarkers="reorder-checkbox"
/>
);
}| Prop | Type | Default |
|---|---|---|
rowMarkers | RowMarkersMode | "none" |
A reorder family mode arms the drag and the keyboard moves. A plain mode ("number", "checkbox", "both") or "none" turns them off. reorderRows runs in every mode.
Drag a row
The press location decides the gesture. In the reorder family, the drag handle zone is the only way to start a reorder. The zone is a 1.25rem column (20 px at the default font size) at the start of the marker cell. In "reorder" mode, it is the whole cell. A press on the handle never changes the selection. A vertical drag that leaves the pressed row reorders it. Press Escape during the drag to cancel.
The number and the checkbox in the marker cell only select rows. A press on them selects a row, and a drag selects a row range. A selection drag never reorders. Shift on the handle never starts a reorder either.
A press on the handle of a checked row drags every checked row. They land together at the drop line and keep their order. A press on an unchecked row drags that row alone and leaves the checks as they are. The marker cells of the dragged rows dim until the drag ends. If the pointer stays near the top or bottom edge, the grid scrolls, so you can reach rows that are not rendered yet.
Move rows from the keyboard
Shift+Alt+PageUp (moveRowsUp) and Shift+Alt+PageDown (moveRowsDown) move rows one place. They act on the checked rows. With no checked row, they act on the rows of the selected range, then on the active row. The gaps between rows stay.
A row at the edge blocks the whole move. The keys need a reorder marker mode, and do nothing in a readOnly grid or while a cell editor is open. With 'across-filters', they do nothing when every checked row is hidden or while "all matching" is on. Each press is one change. With the history add-on, it is one undo step. Remap the keys through the keymap prop.
Move rows from code
reorderRows(rows, to) and moveRowsBy(rows, delta) come from useDataGridActions. If rows moved, both return true. Both address view indexes:
import { useDataGridActions } from "@/components/data-grid/data-grid";
function MoveTools() {
const actions = useDataGridActions();
return (
<>
<button type="button" onClick={() => actions.reorderRows(0, 3)}>
Row 1 to position 4
</button>
<button type="button" onClick={() => actions.moveRowsBy([4, 5], -1)}>
Rows 5 and 6 up
</button>
</>
);
}rows is one view index or a list. to is the final index of the first row. Moving row 0 to index 3 shifts rows 1 to 3 up. A list moves as one block: the rows keep their order and land next to each other. A repeated index counts once. to must leave room for the whole block. moveRowsBy shifts every listed row by delta and keeps the gaps.
Under client pagination, reorderRows and moveRowsBy take page rows, and a move stays inside the shown page. A row, a to, or a shift that leaves the page counts as outside the grid, so the call returns false. from and to in change.ops are indices of the whole data array.
These calls return false, change nothing, and report through onRowActionSkipped with action: "moveRows". The reason tells why:
| Reason | When |
|---|---|
"readOnly" | The grid is readOnly. |
"view-ordered" | A sort is active, also with sortMode="server", or a client filter is active. The sort or filter owns the view order. |
"unloaded-rows" | The grid holds unloaded rows in scroll mode. |
"nothing-to-do" | The drop leaves the rows where they are. The list is empty. An index or to is outside the grid. moveRowsBy shifts a row out of the grid. |
In development, the grid also warns for "view-ordered" and "unloaded-rows".
After a move, the checked rows and the active cell follow their rows. An open editor follows its row too. If the rows of a selected range end up next to each other, the range stays. Otherwise it collapses onto the active cell. The grid announces each move in its live region through labels.markers.reorderAnnouncement for one row and labels.markers.reorderRowsAnnouncement for several rows. Under client pagination, the announced positions count the rows of the shown page, like the row numbers.
Presence highlights in the view-index range form go stale after a move. The row-id range form follows its rows. See Show presence.
Server mode
A move is one change with source: "row-operation". It reaches onDataChange and onSave. change.ops holds one move operation per moved row. In each operation, from is the index before the whole batch and to is the index after it. Apply the operations together with applyChange. A server that applies them one at a time ends with the wrong order.
With sortMode="server", an active sort still blocks a move with the reason "view-ordered". Scroll mode blocks a move while the grid holds unloaded rows.
Related
- Row markers: the marker modes and the handle zone
- Row operations: insert, duplicate, and delete rows
- Shortcut remapping: change the move keys
- Data change events: the shape of the
moveoperation