# ReorderPlugin

> _Since v1.24.0_

Column Reorder Plugin for tbw-grid

Lets users rearrange columns by dragging and dropping column headers. Supports smooth
FLIP animations, fade transitions, or instant reordering. Animation respects the
grid-level `animation.mode` setting.

## Installation

```ts
import { ReorderPlugin } from '@toolbox-web/grid/plugins/reorder-columns';
```

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `Alt + ←` | Move focused column left |
| `Alt + →` | Move focused column right |

## Events

| Event | Detail | Cancelable | Description |
|-------|--------|------------|-------------|
| `column-move` | `{ field, fromIndex, toIndex, columnOrder }` | Yes | Fired when a column move is attempted |

## [Configuration Options](/grid/plugins/reorder-columns/interfaces/reorderconfig.md)

| Option | Type | Description |
| ------ | ---- | ----------- |
| `animation?` | <code><a href="/grid/plugins/reorder-columns/types/reorderanimation/">ReorderAnimation</a></code> | Animation type for column movement. - `false`: No animation, instant reorder - `'flip'`: FLIP animation (slides columns smoothly) - `'fade'`: View Transitions API (cross-fade effect) |
| `animationDuration?` | <code>number</code> | Animation duration in milliseconds. Applies to FLIP animation. View Transitions use browser defaults. |

## Examples

### Basic Drag-and-Drop Reordering

```ts
import { queryGrid } from '@toolbox-web/grid';
import { ReorderPlugin } from '@toolbox-web/grid/plugins/reorder-columns';

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

// Persist column order
grid.on('column-move', ({ columnOrder }) => {
  localStorage.setItem('columnOrder', JSON.stringify(columnOrder));
});
```

### Prevent Moves That Break Group Boundaries

```ts
grid.on('column-move', (detail, e) => {
  if (!isValidMoveWithinGroup(detail.field, detail.fromIndex, detail.toIndex)) {
    e.preventDefault(); // Column snaps back to original position
  }
});
```

## See Also

- [`ReorderConfig`](/grid/plugins/reorder-columns/interfaces/reorderconfig.md) for all configuration options
- [`ColumnMoveDetail`](/grid/plugins/reorder-columns/interfaces/columnmovedetail.md) for the event detail structure
- GroupingColumnsPlugin for column group integration

> **Extends** [BaseGridPlugin](/docs/grid-api-plugin-development-classes-basegridplugin--docs)
>
> Inherited methods like `attach()`, `detach()`, `afterRender()`, etc. are documented in the base class.

## Accessors

### animationDuration

Get animation duration, allowing plugin config override.
Uses base class animationDuration for default.

```ts
readonly animationDuration: number
```

***

## Methods

### getColumnOrder()

Get the current column order from the grid.

```ts
getColumnOrder(): string[]
```

#### Returns

`string[]` - Array of field names in display order

***

### moveColumn()

Move a column to a new position.

```ts
moveColumn(field: string, toIndex: number): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `field` | <code>string</code> | The field name of the column to move |
| `toIndex` | <code>number</code> | The target index |

***

### setColumnOrder()

Set a specific column order.

```ts
setColumnOrder(order: string[]): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `order` | <code>string[]</code> | Array of field names in desired order |

***

### resetColumnOrder()

Reset column order to the original configuration order.

```ts
resetColumnOrder(): void
```

***