Column Reorder Plugin

The Reorder plugin lets users rearrange columns by dragging and dropping column headers. Supports smooth FLIP animations, fade transitions, or instant reordering depending on your preference.

Installation

import '@toolbox-web/grid/features/reorder-columns';

Basic Usage

Just enable the feature and columns become draggable. Users can grab any column header and drop it in a new position. Visual feedback and smooth animations are handled automatically.

TypeScript

import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
  ],
  features: {
    reorderColumns: {
      animation: 'flip',
      animationDuration: 200,
    },
  },
};

// Listen for column moves
grid.on('column-move', ({ field, fromIndex, toIndex }) => {
  console.log(`Moved ${field} from ${fromIndex} to ${toIndex}`);
});

React

import '@toolbox-web/grid-react/features/reorder-columns';
import { DataGrid } from '@toolbox-web/grid-react';
import type { GridConfig } from '@toolbox-web/grid-react';

const gridConfig: GridConfig = {
  columns: [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
  ],
  features: {
    reorderColumns: { animation: 'flip' },
  },
};

function MyGrid({ data }) {
  return (
    <DataGrid
      rows={data}
      gridConfig={gridConfig}
      onColumnMove={(e) => console.log(`Moved ${e.detail.field} from ${e.detail.fromIndex} to ${e.detail.toIndex}`)}
      style={{ height: '400px' }}
    />
  );
}

Alternative: feature prop

You can instead pass columns={[ … ]} and reorderColumns={{ … }} as individual props on <DataGrid>. That form is idiomatic React, but gridConfig keeps the configuration identical across every framework.

Vue

<script setup>
import '@toolbox-web/grid-vue/features/reorder-columns';
import { TbwGrid } from '@toolbox-web/grid-vue';
import type { GridConfig } from '@toolbox-web/grid-vue';

const data = [
  { id: 1, name: 'Alice', email: 'alice@example.com', department: 'Engineering' },
  { id: 2, name: 'Bob', email: 'bob@example.com', department: 'Marketing' },
];

const gridConfig: GridConfig = {
  columns: [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
  ],
  features: {
    reorderColumns: { animation: 'flip' },
  },
};
</script>

<template>
  <TbwGrid :rows="data" :grid-config="gridConfig" style="height: 400px" @column-move="(e) => console.log('Column moved:', e.detail)" />
</template>

Alternative: prop + light-dom columns

You can instead bind :reorder-columns="{ … }" and declare columns with <TbwGridColumn> children. That form is idiomatic Vue, but gridConfig keeps the configuration identical across every framework.

Angular

Define everything inside gridConfig.features, exactly like the other frameworks. The side-effect import registers the feature so the adapter can bridge it.

import '@toolbox-web/grid-angular/features/reorder-columns';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { GridConfig } from '@toolbox-web/grid-angular';

@Component({
  selector: 'app-my-grid',
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="rows"
      [gridConfig]="gridConfig"
      (column-move)="onColumnMove($event)"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [...];

  gridConfig: GridConfig = {
    columns: [
      { field: 'id', header: 'ID' },
      { field: 'name', header: 'Name' },
      { field: 'email', header: 'Email' },
      { field: 'department', header: 'Department' },
    ],
    features: {
      reorderColumns: { animation: 'flip' },
    },
  };

  onColumnMove(e: CustomEvent) {
    console.log(`Moved ${e.detail.field} from ${e.detail.fromIndex} to ${e.detail.toIndex}`);
  }
}

Alternative: per-feature directive

You can instead import GridReorderColumnsDirective and bind [reorderColumns] directly on <tbw-grid>. That form gives a compile-time check that the feature is imported, but gridConfig.features above is the recommended, framework-consistent approach.

Demos

Default Reorder

REORDER

AnimationReorder animation style

flipslidefadenone

Duration (ms)Animation duration in ms

200

Show source

Drag column headers to reorder them. Use the controls below to experiment with different animation types and durations.

Configuration Options

See ReorderConfig for the full list of options and defaults.

Animation Examples

// No animation - instant reorder
features: { reorderColumns: { animation: false } }

// FLIP animation with custom duration
features: { reorderColumns: { animation: 'flip', animationDuration: 300 } }

// View Transitions API fade effect
features: { reorderColumns: { animation: 'fade' } }

Locking Individual Columns

Set lockPosition: true on any column to prevent users from dragging it — both in the header row and in the Column Visibility panel. Programmatic reorder via grid.setColumnOrder() still works.

columns: [
  { field: 'id', header: 'ID', lockPosition: true }, // cannot be moved
  { field: 'name', header: 'Name' },
  { field: 'email', header: 'Email' },
]

Events

Drag column headers to reorder them.

Event Log:Clear

Show source

Event	Detail	Cancelable	Description
column-move	{ field, fromIndex, toIndex, columnOrder }	Yes	Fired when a column move is attempted. Call preventDefault() to block the move.

Keyboard Shortcuts

Key	Action
Alt + ←	Move focused column left
Alt + →	Move focused column right

Column Group Drag

When Column Grouping is also active, group header cells become draggable. Dragging a group header moves all columns in that fragment as a block. If a group is fragmented (split across non-contiguous positions), each fragment can be dragged independently.

Accessibility

The plugin satisfies WCAG 2.2 SC 2.5.7 Dragging Movements: every column move that can be made by dragging can also be made with a single pointer that never drags.

• Single-pointer alternative — opening a header’s context menu (right-click, long-press, or Shift + F10) offers Move left, Move right, Move to start and Move to end, each a single click. Directions that would run off the edge, or past a lockPosition column, are rendered disabled rather than hidden, so the menu shape stays stable.
• No reserved chrome — the trigger is the header cell you would have dragged anyway, so the alternative costs nothing in header width and is invisible until asked for. SC 2.5.7 requires the alternative to exist and be pointer-operable, not to be permanently on screen.
• Merges with the Context Menu plugin — when Context Menu is registered, these entries are contributed to it as a grouped block after the pinning actions. Without it, the plugin opens its own small menu instead of stacking a second one.
• Menu semantics — the pop-up is a role="group" of plain buttons with an accessible name naming the column. Focus moves to the first enabled entry on open, Escape closes it, and moving focus outside dismisses it.
• Keyboard — Alt + ← / → move the focused column, satisfying SC 2.1.1 Keyboard. Per the W3C, a keyboard equivalent alone does not satisfy SC 2.5.7 — that is why the click path exists as well.

Showing the control inline

Set a11y.dragAlternatives: 'inline' on the grid config to additionally render a move button in every movable header, revealed on hover or focus. It is more discoverable, at the cost of roughly 24px of width reserved in each affected header cell.

gridConfig = { a11y: { dragAlternatives: 'inline' } };

Pointers that cannot hover (touch, most switch devices) always get the inline button regardless of this setting — there is nothing for them to hover in order to reveal it. See Pointer Alternatives to Dragging for the grid-wide picture.

See Also

• Pinned Columns — Sticky columns
• Column Visibility — Show/hide columns
• Column Groups — Group column headers