Column Reordering
Let users rearrange columns by dragging a column header and dropping it at a new position. The grid shows a visual drop indicator while dragging. Keyboard users get Move left and Move right in each column's header menu.
Live Demo
The demo above uses Radix UI for styling. To see this feature with the Fluent UI implementation, click "Open in online demo" below the demo.
Quick Example
- React
import { OGrid } from '@alaarab/ogrid-react-radix';
import type { IColumnDef } from '@alaarab/ogrid-react-radix';
interface Person {
id: number;
name: string;
email: string;
department: string;
salary: number;
status: string;
}
const columns: IColumnDef<Person>[] = [
{ columnId: 'name', name: 'Name' },
{ columnId: 'email', name: 'Email' },
{ columnId: 'department', name: 'Department' },
{ columnId: 'salary', name: 'Salary', type: 'numeric',
valueFormatter: (v) => `$${Number(v).toLocaleString()}` },
{ columnId: 'status', name: 'Status' },
];
function App() {
return (
<OGrid
columns={columns}
data={people}
getRowId={(p) => p.id}
columnReorder
defaultPageSize={10}
/>
);
}
The OGrid component has the same props across all React UI packages. To switch, just change the import:
- Radix (lightweight, default):
from '@alaarab/ogrid-react-radix' - Fluent UI (Microsoft 365 / SPFx):
from '@alaarab/ogrid-react-fluent'- wrap in<FluentProvider>
Drag any column header to rearrange it. A vertical indicator line shows where the column will be placed.
How It Works
Set columnReorder to true on the grid to enable drag-and-drop column reordering. When a user presses and drags a column header at least 5 pixels horizontally, the grid enters reorder mode:
- A vertical drop indicator appears between columns as the user drags.
- On mouse-up, the column is moved to the target position.
- The grid fires
onColumnOrderChangewith the updated order array.
OGrid supports both uncontrolled and controlled column order:
- Uncontrolled -- the grid manages column order internally. Just set
columnReorderand it works. AddonColumnOrderChangeto hear about changes (for example, to save them). - Controlled -- you own the state. Pass
columnOrderandonColumnOrderChangeto the grid. The grid shows the order you pass, so update it from the callback.
onColumnOrderChange receives every column id, hidden columns included, in their new order.
Keyboard
Each column's header menu (the ⋮ button, or ArrowDown when the button has focus) has Move left and Move right when columnReorder is on. Each moves the column one position, past the next visible column, and fires onColumnOrderChange the same way a drag does. An item is disabled when the column is already at the edge of its pin zone. After the move, focus returns to the column's menu button, so pressing ArrowDown again repeats it.
Saving the order
The order is a plain array of column ids, so you can store it anywhere:
const [columnOrder, setColumnOrder] = useState<string[] | undefined>(
() => JSON.parse(localStorage.getItem('report-columns') ?? 'null') ?? undefined,
);
<OGrid
columns={columns}
data={rows}
getRowId={(r) => r.id}
columnReorder
columnOrder={columnOrder}
onColumnOrderChange={(order) => {
setColumnOrder(order);
localStorage.setItem('report-columns', JSON.stringify(order));
}}
/>
Columns missing from a saved order (for example, columns added in a later release) show after the listed ones in definition order, and ids that no longer exist are ignored.
Controlled Column Order
- React
import { useState } from 'react';
import { OGrid } from '@alaarab/ogrid-react-radix';
function App() {
const [columnOrder, setColumnOrder] = useState([
'name', 'email', 'department', 'salary', 'status',
]);
return (
<OGrid
columns={columns}
data={people}
getRowId={(p) => p.id}
columnReorder
columnOrder={columnOrder}
onColumnOrderChange={setColumnOrder}
defaultPageSize={10}
/>
);
}
With Pinned Columns
Pinned columns can only be reordered within their own pinning zone. A left-pinned column cannot be dragged into the unpinned zone, and vice versa. This prevents accidental loss of pinned state during reorder.
const columns = [
{ columnId: 'id', name: 'ID', pinned: 'left' },
{ columnId: 'name', name: 'Name', pinned: 'left' },
{ columnId: 'email', name: 'Email' },
{ columnId: 'department', name: 'Department' },
{ columnId: 'salary', name: 'Salary' },
];
<OGrid
columns={columns}
data={people}
getRowId={(p) => p.id}
columnReorder
defaultPageSize={10}
/>
In this example, "ID" and "Name" can be swapped with each other but cannot be dragged into the unpinned section. The unpinned columns ("Email", "Department", "Salary") can be freely rearranged among themselves.
Edge Cases
- Column groups: Group headers are not draggable. Only leaf columns (with a
columnId) participate in reordering. A leaf moved out of its group splits the group header into one cell over each run of its columns, so headers always sit over their own columns. - Hidden columns: A hidden column keeps its place in the order while others move around it, and comes back there when shown.
- Frozen columns (
frozenColumns): The first N displayed columns are frozen, so moving a column into those positions freezes it. - Resize handle zone: The rightmost 8 pixels of each header cell are reserved for column resizing. Dragging in that zone starts a resize, not a reorder.
- Minimum drag distance: A 5-pixel horizontal threshold prevents accidental reorders from clicks.
Grid API
Column order can be read and updated programmatically through the Grid API:
const gridRef = useRef<IOGridApi<Row>>(null);
// Get the current column display order
const order = gridRef.current.getColumnOrder();
// ['name', 'department', 'email', 'salary', 'status']
// Programmatically set column order
gridRef.current.setColumnOrder(['department', 'name', 'email', 'salary', 'status']);
// Save and restore via column state
const state = gridRef.current.getColumnState();
// state.columnOrder to ['name', 'department', 'email', 'salary', 'status']
localStorage.setItem('gridState', JSON.stringify(state));
// Restore on mount
const saved = JSON.parse(localStorage.getItem('gridState'));
gridRef.current.applyColumnState(saved);
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
columnReorder | boolean | false | Enable drag-and-drop column reordering. |
columnOrder | string[] | -- | Controlled column display order (array of column ids). |
onColumnOrderChange | (order: string[]) => void | -- | Called with the full new order when a column is moved by drag, the header menu, or the Grid API. |
Grid API Methods
| Method | Signature | Description |
|---|---|---|
getColumnOrder | () => string[] | Returns the current column display order. |
setColumnOrder | (order: string[]) => void | Programmatically set column display order. |
getColumnState | () => IGridColumnState | Returns full column state including order, widths, sort, filters. |
applyColumnState | (state: Partial<IGridColumnState>) => void | Restores column state (including order). |
Combine columnReorder with columnChooser and sideBar for a full column management experience -- users can show/hide, reorder, and resize columns to build their ideal layout.
Related
- Column Pinning -- pin columns that stay fixed during reorder
- Column Chooser -- show/hide columns
- Grid API -- save and restore column order via API
- Sidebar -- manage columns from a side panel