Column DnD Table

Drag-and-drop column reordering with composable primitives.

Drag column headers to reorder them, wired through DataTableColumnDndProvider on top of @dnd-kit. Unlike row DnD, column DnD is safe to combine with sorting, filtering, and virtualization — the user’s column order is independent of the row model.

Overview

Open in

1
"use client"
2

3
import * as React from "react"
4
import { DataTableRoot } from "@/components/niko-table/core/data-table-root"
5
import { DataTable } from "@/components/niko-table/core/data-table"
6
import { DataTableEmptyBody } from "@/components/niko-table/core/data-table-structure"
7
import {
8
  DataTableDndHeader,
9
  DataTableDndColumnBody,
10
} from "@/components/niko-table/core/data-table-dnd-structure"
11
import { DataTableColumnDndProvider } from "@/components/niko-table/components/data-table-column-dnd"
12
import {
13
  DataTableEmptyIcon,
14
  DataTableEmptyMessage,
15
  DataTableEmptyTitle,
16
  DataTableEmptyDescription,
17
} from "@/components/niko-table/components/data-table-empty-state"
18
import { DataTableSearchFilter } from "@/components/niko-table/components/data-table-search-filter"
19
import { DataTableToolbarSection } from "@/components/niko-table/components/data-table-toolbar-section"
20
import { DataTableViewDndMenu } from "@/components/niko-table/components/data-table-view-dnd-menu"
21
import type { DataTableColumnDef } from "@/components/niko-table/types"
22
import { Badge } from "@/components/ui/badge"
23
import { Inbox } from "lucide-react"
24

25
// Types
26
type Employee = {
27
  id: string
28
  name: string
29
  department: string
30
  role: string
31
  location: string
32
  status: "active" | "on-leave" | "remote"
33
}
34

35
// Sample data
36
const data: Employee[] = [
37
  {
38
    id: "EMP-001",
39
    name: "Alice Johnson",
40
    department: "Engineering",
41
    role: "Senior Developer",
42
    location: "New York",
43
    status: "active",
44
  },
45
  {
46
    id: "EMP-002",
47
    name: "Bob Smith",
48
    department: "Design",
49
    role: "UI Designer",
50
    location: "San Francisco",
51
    status: "remote",
52
  },
53
  {
54
    id: "EMP-003",
55
    name: "Carol Williams",
56
    department: "Marketing",
57
    role: "Marketing Lead",
58
    location: "Chicago",
59
    status: "active",
60
  },
61
  {
62
    id: "EMP-004",
63
    name: "David Brown",
64
    department: "Engineering",
65
    role: "Backend Developer",
66
    location: "Austin",
67
    status: "on-leave",
68
  },
69
  {
70
    id: "EMP-005",
71
    name: "Eva Martinez",
72
    department: "Product",
73
    role: "Product Manager",
74
    location: "Seattle",
75
    status: "active",
76
  },
77
  {
78
    id: "EMP-006",
79
    name: "Frank Lee",
80
    department: "Engineering",
81
    role: "DevOps Engineer",
82
    location: "Denver",
83
    status: "remote",
84
  },
85
  {
86
    id: "EMP-007",
87
    name: "Grace Kim",
88
    department: "Design",
89
    role: "UX Researcher",
90
    location: "Portland",
91
    status: "active",
92
  },
93
  {
94
    id: "EMP-008",
95
    name: "Henry Davis",
96
    department: "Sales",
97
    role: "Account Executive",
98
    location: "Boston",
99
    status: "active",
100
  },
101
]
102

103
// Status badge variant helper
104
const getStatusVariant = (status: Employee["status"]) => {
105
  switch (status) {
106
    case "active":
107
      return "default"
108
    case "remote":
109
      return "secondary"
110
    case "on-leave":
111
      return "outline"
112
    default:
113
      return "secondary"
114
  }
115
}
116

117
// Column definitions
118
const columns: DataTableColumnDef<Employee>[] = [
119
  {
120
    accessorKey: "id",
121
    id: "id",
122
    header: "Employee ID",
123
    size: 120,
124
  },
125
  {
126
    accessorKey: "name",
127
    id: "name",
128
    header: "Name",
129
    size: 160,
130
    cell: ({ row }) => (
131
      <div className="font-medium">{row.getValue("name")}</div>
132
    ),
133
  },
134
  {
135
    accessorKey: "department",
136
    id: "department",
137
    header: "Department",
138
    size: 140,
139
  },
140
  {
141
    accessorKey: "role",
142
    id: "role",
143
    header: "Role",
144
    size: 170,
145
  },
146
  {
147
    accessorKey: "location",
148
    id: "location",
149
    header: "Location",
150
    size: 140,
151
  },
152
  {
153
    accessorKey: "status",
154
    id: "status",
155
    header: "Status",
156
    size: 110,
157
    cell: ({ row }) => {
158
      const status = row.getValue("status") as Employee["status"]
159
      return <Badge variant={getStatusVariant(status)}>{status}</Badge>
160
    },
161
  },
162
]
163

164
const initialColumnOrder = columns.map(c => c.id as string)
165

166
export default function ColumnDndExample() {
167
  const [columnOrder, setColumnOrder] =
168
    React.useState<string[]>(initialColumnOrder)
169

170
  return (
171
    <DataTableRoot
172
      data={data}
173
      columns={columns}
174
      state={{ columnOrder }}
175
      onColumnOrderChange={setColumnOrder}
176
    >
177
      <DataTableColumnDndProvider
178
        columnOrder={columnOrder}
179
        onColumnOrderChange={setColumnOrder}
180
      >
181
        {/*
182
         * Two reorder surfaces share one `columnOrder`:
183
         *   1. Drag column headers (DataTableColumnDndProvider)
184
         *   2. Drag rows in the View menu (DataTableViewDndMenu)
185
         * Either updates the same state, so both stay in sync.
186
         */}
187
        <DataTableToolbarSection className="justify-between">
188
          <DataTableSearchFilter placeholder="Search employees..." />
189
          <DataTableViewDndMenu
190
            columnOrder={columnOrder}
191
            onColumnOrderChange={setColumnOrder}
192
            onReset={() => setColumnOrder(initialColumnOrder)}
193
          />
194
        </DataTableToolbarSection>
195
        <DataTable>
196
          <DataTableDndHeader />
197
          <DataTableDndColumnBody>
198
            <DataTableEmptyBody>
199
              <DataTableEmptyMessage>
200
                <DataTableEmptyIcon>
201
                  <Inbox className="size-12" />
202
                </DataTableEmptyIcon>
203
                <DataTableEmptyTitle>No employees found</DataTableEmptyTitle>
204
                <DataTableEmptyDescription>
205
                  Try a different search.
206
                </DataTableEmptyDescription>
207
              </DataTableEmptyMessage>
208
            </DataTableEmptyBody>
209
          </DataTableDndColumnBody>
210
        </DataTable>
211
      </DataTableColumnDndProvider>
212
    </DataTableRoot>
213
  )
214
}

Employee ID	Name	Department	Role	Location	Status
EMP-001	Alice Johnson	Engineering	Senior Developer	New York	active
EMP-002	Bob Smith	Design	UI Designer	San Francisco	remote
EMP-003	Carol Williams	Marketing	Marketing Lead	Chicago	active
EMP-004	David Brown	Engineering	Backend Developer	Austin	on-leave
EMP-005	Eva Martinez	Product	Product Manager	Seattle	active
EMP-006	Frank Lee	Engineering	DevOps Engineer	Denver	remote
EMP-007	Grace Kim	Design	UX Researcher	Portland	active
EMP-008	Henry Davis	Sales	Account Executive	Boston	active

Preview with Controlled State

Open in

1
"use client"
2

3
import * as React from "react"
4
import type { VisibilityState } from "@tanstack/react-table"
5
import { DataTableRoot } from "@/components/niko-table/core/data-table-root"
6
import { DataTable } from "@/components/niko-table/core/data-table"
7
import { DataTableEmptyBody } from "@/components/niko-table/core/data-table-structure"
8
import {
9
  DataTableDndHeader,
10
  DataTableDndColumnBody,
11
} from "@/components/niko-table/core/data-table-dnd-structure"
12
import { DataTableColumnDndProvider } from "@/components/niko-table/components/data-table-column-dnd"
13
import {
14
  DataTableEmptyIcon,
15
  DataTableEmptyMessage,
16
  DataTableEmptyTitle,
17
  DataTableEmptyDescription,
18
} from "@/components/niko-table/components/data-table-empty-state"
19
import { DataTableSearchFilter } from "@/components/niko-table/components/data-table-search-filter"
20
import { DataTableToolbarSection } from "@/components/niko-table/components/data-table-toolbar-section"
21
import { DataTableViewDndMenu } from "@/components/niko-table/components/data-table-view-dnd-menu"
22
import type { DataTableColumnDef } from "@/components/niko-table/types"
23
import { Badge } from "@/components/ui/badge"
24
import { Button } from "@/components/ui/button"
25
import {
26
  Card,
27
  CardAction,
28
  CardContent,
29
  CardDescription,
30
  CardHeader,
31
  CardTitle,
32
} from "@/components/ui/card"
33
import { Inbox } from "lucide-react"
34

35
// Types
36
type Employee = {
37
  id: string
38
  name: string
39
  department: string
40
  role: string
41
  location: string
42
  status: "active" | "on-leave" | "remote"
43
}
44

45
// Sample data
46
const data: Employee[] = [
47
  {
48
    id: "EMP-001",
49
    name: "Alice Johnson",
50
    department: "Engineering",
51
    role: "Senior Developer",
52
    location: "New York",
53
    status: "active",
54
  },
55
  {
56
    id: "EMP-002",
57
    name: "Bob Smith",
58
    department: "Design",
59
    role: "UI Designer",
60
    location: "San Francisco",
61
    status: "remote",
62
  },
63
  {
64
    id: "EMP-003",
65
    name: "Carol Williams",
66
    department: "Marketing",
67
    role: "Marketing Lead",
68
    location: "Chicago",
69
    status: "active",
70
  },
71
  {
72
    id: "EMP-004",
73
    name: "David Brown",
74
    department: "Engineering",
75
    role: "Backend Developer",
76
    location: "Austin",
77
    status: "on-leave",
78
  },
79
  {
80
    id: "EMP-005",
81
    name: "Eva Martinez",
82
    department: "Product",
83
    role: "Product Manager",
84
    location: "Seattle",
85
    status: "active",
86
  },
87
  {
88
    id: "EMP-006",
89
    name: "Frank Lee",
90
    department: "Engineering",
91
    role: "DevOps Engineer",
92
    location: "Denver",
93
    status: "remote",
94
  },
95
  {
96
    id: "EMP-007",
97
    name: "Grace Kim",
98
    department: "Design",
99
    role: "UX Researcher",
100
    location: "Portland",
101
    status: "active",
102
  },
103
  {
104
    id: "EMP-008",
105
    name: "Henry Davis",
106
    department: "Sales",
107
    role: "Account Executive",
108
    location: "Boston",
109
    status: "active",
110
  },
111
]
112

113
// Status badge variant helper
114
const getStatusVariant = (status: Employee["status"]) => {
115
  switch (status) {
116
    case "active":
117
      return "default"
118
    case "remote":
119
      return "secondary"
120
    case "on-leave":
121
      return "outline"
122
    default:
123
      return "secondary"
124
  }
125
}
126

127
// Column definitions
128
const columns: DataTableColumnDef<Employee>[] = [
129
  {
130
    accessorKey: "id",
131
    id: "id",
132
    header: "Employee ID",
133
    size: 120,
134
  },
135
  {
136
    accessorKey: "name",
137
    id: "name",
138
    header: "Name",
139
    size: 160,
140
    cell: ({ row }) => (
141
      <div className="font-medium">{row.getValue("name")}</div>
142
    ),
143
  },
144
  {
145
    accessorKey: "department",
146
    id: "department",
147
    header: "Department",
148
    size: 140,
149
  },
150
  {
151
    accessorKey: "role",
152
    id: "role",
153
    header: "Role",
154
    size: 170,
155
  },
156
  {
157
    accessorKey: "location",
158
    id: "location",
159
    header: "Location",
160
    size: 140,
161
  },
162
  {
163
    accessorKey: "status",
164
    id: "status",
165
    header: "Status",
166
    size: 110,
167
    cell: ({ row }) => {
168
      const status = row.getValue("status") as Employee["status"]
169
      return <Badge variant={getStatusVariant(status)}>{status}</Badge>
170
    },
171
  },
172
]
173

174
const initialColumnOrder = columns.map(c => c.id as string)
175

176
export default function ColumnDndStateExample() {
177
  const [columnOrder, setColumnOrder] =
178
    React.useState<string[]>(initialColumnOrder)
179
  const [columnVisibility, setColumnVisibility] =
180
    React.useState<VisibilityState>({})
181
  const [globalFilter, setGlobalFilter] = React.useState<string | object>("")
182

183
  const resetAll = () => {
184
    setColumnOrder(initialColumnOrder)
185
    setColumnVisibility({})
186
    setGlobalFilter("")
187
  }
188

189
  return (
190
    <div className="w-full space-y-4">
191
      <DataTableRoot
192
        data={data}
193
        columns={columns}
194
        state={{ columnOrder, columnVisibility, globalFilter }}
195
        onColumnOrderChange={setColumnOrder}
196
        onColumnVisibilityChange={setColumnVisibility}
197
        onGlobalFilterChange={setGlobalFilter}
198
      >
199
        <DataTableColumnDndProvider
200
          columnOrder={columnOrder}
201
          onColumnOrderChange={setColumnOrder}
202
        >
203
          {/*
204
           * Two reorder surfaces share one `columnOrder`:
205
           *   1. Drag column headers (DataTableColumnDndProvider)
206
           *   2. Drag rows in the View menu (DataTableViewDndMenu)
207
           * Either updates the same state, so both stay in sync.
208
           * The View menu also toggles visibility and exposes a Reset.
209
           */}
210
          <DataTableToolbarSection className="justify-between">
211
            <DataTableSearchFilter placeholder="Search employees..." />
212
            <DataTableViewDndMenu
213
              columnOrder={columnOrder}
214
              onColumnOrderChange={setColumnOrder}
215
              onReset={resetAll}
216
            />
217
          </DataTableToolbarSection>
218
          <DataTable>
219
            <DataTableDndHeader />
220
            <DataTableDndColumnBody>
221
              <DataTableEmptyBody>
222
                <DataTableEmptyMessage>
223
                  <DataTableEmptyIcon>
224
                    <Inbox className="size-12" />
225
                  </DataTableEmptyIcon>
226
                  <DataTableEmptyTitle>No employees found</DataTableEmptyTitle>
227
                  <DataTableEmptyDescription>
228
                    Try a different search.
229
                  </DataTableEmptyDescription>
230
                </DataTableEmptyMessage>
231
              </DataTableEmptyBody>
232
            </DataTableDndColumnBody>
233
          </DataTable>
234
        </DataTableColumnDndProvider>
235
      </DataTableRoot>
236

237
      {/* State Display */}
238
      <Card>
239
        <CardHeader>
240
          <CardTitle>Column DnD State</CardTitle>
241
          <CardDescription>
242
            Header drag, view-menu drag, visibility toggles, and search — all
243
            live state.
244
          </CardDescription>
245
          <CardAction>
246
            <Button variant="outline" size="sm" onClick={resetAll}>
247
              Reset
248
            </Button>
249
          </CardAction>
250
        </CardHeader>
251
        <CardContent>
252
          <div className="grid gap-2 text-xs text-muted-foreground">
253
            <div className="flex justify-between">
254
              <span className="font-medium">Total Columns:</span>
255
              <span className="text-foreground">{columnOrder.length}</span>
256
            </div>
257
            <div className="flex justify-between">
258
              <span className="font-medium">Current Order:</span>
259
              <span className="text-foreground">{columnOrder.join(" → ")}</span>
260
            </div>
261
            <div className="flex justify-between">
262
              <span className="font-medium">Hidden:</span>
263
              <span className="text-foreground">
264
                {Object.entries(columnVisibility)
265
                  .filter(([, v]) => !v)
266
                  .map(([k]) => k)
267
                  .join(", ") || "none"}
268
              </span>
269
            </div>
270
            <div className="flex justify-between">
271
              <span className="font-medium">Search:</span>
272
              <span className="text-foreground">
273
                {typeof globalFilter === "string" && globalFilter
274
                  ? globalFilter
275
                  : "—"}
276
              </span>
277
            </div>
278
          </div>
279

280
          <details className="mt-4 border-t pt-4">
281
            <summary className="cursor-pointer text-xs font-medium hover:text-foreground">
282
              View Full State
283
            </summary>
284
            <pre className="mt-2 overflow-auto rounded bg-muted p-2 text-xs">
285
              {JSON.stringify(
286
                { columnOrder, columnVisibility, globalFilter },
287
                null,
288
                2,
289
              )}
290
            </pre>
291
          </details>
292
        </CardContent>
293
      </Card>
294
    </div>
295
  )
296
}

Employee ID	Name	Department	Role	Location	Status
EMP-001	Alice Johnson	Engineering	Senior Developer	New York	active
EMP-002	Bob Smith	Design	UI Designer	San Francisco	remote
EMP-003	Carol Williams	Marketing	Marketing Lead	Chicago	active
EMP-004	David Brown	Engineering	Backend Developer	Austin	on-leave
EMP-005	Eva Martinez	Product	Product Manager	Seattle	active
EMP-006	Frank Lee	Engineering	DevOps Engineer	Denver	remote
EMP-007	Grace Kim	Design	UX Researcher	Portland	active
EMP-008	Henry Davis	Sales	Account Executive	Boston	active

Column DnD State

Header drag, view-menu drag, visibility toggles, and search — all live state.

Total Columns:6

Current Order:id → name → department → role → location → status

Hidden:none

Search:—

View Full State

{
  "columnOrder": [
    "id",
    "name",
    "department",
    "role",
    "location",
    "status"
  ],
  "columnVisibility": {},
  "globalFilter": ""
}

Virtualized Column DnD

For large datasets, use DataTableVirtualizedDndHeader and DataTableVirtualizedDndColumnBody which combine row virtualization with column drag-and-drop.

Open in

1
"use client"
2

3
import * as React from "react"
4
import { DataTableRoot } from "@/components/niko-table/core/data-table-root"
5
import { DataTable } from "@/components/niko-table/core/data-table"
6
import { DataTableVirtualizedEmptyBody } from "@/components/niko-table/core/data-table-virtualized-structure"
7
import {
8
  DataTableVirtualizedDndHeader,
9
  DataTableVirtualizedDndColumnBody,
10
} from "@/components/niko-table/core/data-table-virtualized-dnd-structure"
11
import { DataTableColumnDndProvider } from "@/components/niko-table/components/data-table-column-dnd"
12
import {
13
  DataTableEmptyIcon,
14
  DataTableEmptyMessage,
15
  DataTableEmptyTitle,
16
  DataTableEmptyDescription,
17
} from "@/components/niko-table/components/data-table-empty-state"
18
import { DataTableSearchFilter } from "@/components/niko-table/components/data-table-search-filter"
19
import { DataTableToolbarSection } from "@/components/niko-table/components/data-table-toolbar-section"
20
import { DataTableViewDndMenu } from "@/components/niko-table/components/data-table-view-dnd-menu"
21
import type { DataTableColumnDef } from "@/components/niko-table/types"
22
import { Badge } from "@/components/ui/badge"
23
import { Inbox } from "lucide-react"
24

25
// Types
26
type Employee = {
27
  id: string
28
  name: string
29
  email: string
30
  department: string
31
  role: string
32
  location: string
33
  status: "active" | "on-leave" | "remote"
34
  salary: number
35
}
36

37
// Generate large dataset for virtualization demo
38
const generateEmployees = (count: number): Employee[] => {
39
  const firstNames = [
40
    "Alice",
41
    "Bob",
42
    "Carol",
43
    "David",
44
    "Eva",
45
    "Frank",
46
    "Grace",
47
    "Henry",
48
    "Ivy",
49
    "Jack",
50
    "Karen",
51
    "Leo",
52
    "Mia",
53
    "Noah",
54
    "Olivia",
55
    "Paul",
56
    "Quinn",
57
    "Ruby",
58
    "Sam",
59
    "Tina",
60
  ]
61
  const lastNames = [
62
    "Johnson",
63
    "Smith",
64
    "Williams",
65
    "Brown",
66
    "Martinez",
67
    "Lee",
68
    "Kim",
69
    "Davis",
70
    "Wilson",
71
    "Taylor",
72
    "Anderson",
73
    "Thomas",
74
    "Jackson",
75
    "White",
76
    "Harris",
77
  ]
78
  const departments = [
79
    "Engineering",
80
    "Design",
81
    "Marketing",
82
    "Sales",
83
    "Product",
84
    "HR",
85
    "Finance",
86
    "Operations",
87
  ]
88
  const roles = [
89
    "Senior Developer",
90
    "UI Designer",
91
    "Marketing Lead",
92
    "Backend Developer",
93
    "Product Manager",
94
    "DevOps Engineer",
95
    "UX Researcher",
96
    "Account Executive",
97
    "Data Analyst",
98
    "QA Engineer",
99
  ]
100
  const locations = [
101
    "New York",
102
    "San Francisco",
103
    "Chicago",
104
    "Austin",
105
    "Seattle",
106
    "Denver",
107
    "Portland",
108
    "Boston",
109
    "Miami",
110
    "Atlanta",
111
  ]
112
  const statuses: Employee["status"][] = ["active", "on-leave", "remote"]
113

114
  return Array.from({ length: count }, (_, i) => {
115
    const firstName = firstNames[Math.floor(Math.random() * firstNames.length)]
116
    const lastName = lastNames[Math.floor(Math.random() * lastNames.length)]
117
    return {
118
      id: `EMP-${String(i + 1).padStart(4, "0")}`,
119
      name: `${firstName} ${lastName}`,
120
      email: `${firstName.toLowerCase()}.${lastName.toLowerCase()}${i}@company.com`,
121
      department: departments[Math.floor(Math.random() * departments.length)],
122
      role: roles[Math.floor(Math.random() * roles.length)],
123
      location: locations[Math.floor(Math.random() * locations.length)],
124
      status: statuses[Math.floor(Math.random() * statuses.length)],
125
      salary: Math.floor(Math.random() * 100000) + 50000,
126
    }
127
  })
128
}
129

130
const data = generateEmployees(500)
131

132
// Status badge variant helper
133
const getStatusVariant = (status: Employee["status"]) => {
134
  switch (status) {
135
    case "active":
136
      return "default"
137
    case "remote":
138
      return "secondary"
139
    case "on-leave":
140
      return "outline"
141
    default:
142
      return "secondary"
143
  }
144
}
145

146
// Column definitions — all columns need explicit `id` for column ordering
147
const columns: DataTableColumnDef<Employee>[] = [
148
  {
149
    accessorKey: "id",
150
    id: "id",
151
    header: "Employee ID",
152
    size: 120,
153
  },
154
  {
155
    accessorKey: "name",
156
    id: "name",
157
    header: "Name",
158
    size: 170,
159
    cell: ({ row }) => (
160
      <div className="font-medium">{row.getValue("name")}</div>
161
    ),
162
  },
163
  {
164
    accessorKey: "email",
165
    id: "email",
166
    header: "Email",
167
    size: 250,
168
    cell: ({ row }) => (
169
      <div className="text-muted-foreground">{row.getValue("email")}</div>
170
    ),
171
  },
172
  {
173
    accessorKey: "department",
174
    id: "department",
175
    header: "Department",
176
    size: 140,
177
  },
178
  {
179
    accessorKey: "role",
180
    id: "role",
181
    header: "Role",
182
    size: 170,
183
  },
184
  {
185
    accessorKey: "location",
186
    id: "location",
187
    header: "Location",
188
    size: 140,
189
  },
190
  {
191
    accessorKey: "status",
192
    id: "status",
193
    header: "Status",
194
    size: 110,
195
    cell: ({ row }) => {
196
      const status = row.getValue("status") as Employee["status"]
197
      return <Badge variant={getStatusVariant(status)}>{status}</Badge>
198
    },
199
  },
200
  {
201
    accessorKey: "salary",
202
    id: "salary",
203
    header: "Salary",
204
    size: 120,
205
    cell: ({ row }) => {
206
      const salary = row.getValue("salary") as number
207
      return <div className="font-mono">${salary.toLocaleString()}</div>
208
    },
209
  },
210
]
211

212
const initialColumnOrder = columns.map(c => c.id as string)
213

214
export default function VirtualizedColumnDndExample() {
215
  const [columnOrder, setColumnOrder] =
216
    React.useState<string[]>(initialColumnOrder)
217

218
  return (
219
    <DataTableRoot
220
      data={data}
221
      columns={columns}
222
      state={{ columnOrder }}
223
      onColumnOrderChange={setColumnOrder}
224
    >
225
      <DataTableColumnDndProvider
226
        columnOrder={columnOrder}
227
        onColumnOrderChange={setColumnOrder}
228
      >
229
        {/*
230
         * Two reorder surfaces, one state — header drag and view-menu drag
231
         * both update the same `columnOrder`. Search filters the 500-row
232
         * virtualized dataset on the fly.
233
         */}
234
        <DataTableToolbarSection className="justify-between">
235
          <DataTableSearchFilter placeholder="Search employees..." />
236
          <DataTableViewDndMenu
237
            columnOrder={columnOrder}
238
            onColumnOrderChange={setColumnOrder}
239
            onReset={() => setColumnOrder(initialColumnOrder)}
240
          />
241
        </DataTableToolbarSection>
242
        <DataTable height={500}>
243
          <DataTableVirtualizedDndHeader />
244
          <DataTableVirtualizedDndColumnBody estimateSize={40} overscan={10}>
245
            <DataTableVirtualizedEmptyBody>
246
              <DataTableEmptyMessage>
247
                <DataTableEmptyIcon>
248
                  <Inbox className="size-12" />
249
                </DataTableEmptyIcon>
250
                <DataTableEmptyTitle>No employees found</DataTableEmptyTitle>
251
                <DataTableEmptyDescription>
252
                  Try a different search.
253
                </DataTableEmptyDescription>
254
              </DataTableEmptyMessage>
255
            </DataTableVirtualizedEmptyBody>
256
          </DataTableVirtualizedDndColumnBody>
257
        </DataTable>
258
      </DataTableColumnDndProvider>
259
    </DataTableRoot>
260
  )
261
}

Introduction

Column DnD lets users reorder table columns by dragging headers. Built with @dnd-kit and composable primitives following the shadcn/ui open-code pattern.

Installation

Install the DataTable core and column DnD add-ons. Add data-table-view-dnd-menu and data-table-search-filter for the toolbar shown in the example:

pnpm dlx shadcn@latest add @niko-table/data-table @niko-table/data-table-column-dnd @niko-table/data-table-view-dnd-menu @niko-table/data-table-search-filter

First time using @niko-table? See the Installation Guide to set up the registry.

For other add-ons or manual copy-paste, see the Installation Guide.

Basic Column DnD

Three components work together:

DataTableColumnDndProvider — Wraps the table with horizontal DnD context
DataTableDndHeader — Renders headers as draggable items
DataTableDndColumnBody — Cells follow column drag position

1
const [columnOrder, setColumnOrder] = React.useState<string[]>(() =>
2
  columns.map(c => c.id as string),
3
)
4

5
return (
6
  <DataTableRoot
7
    data={data}
8
    columns={columns}
9
    state={{ columnOrder }}
10
    onColumnOrderChange={setColumnOrder}
11
  >
12
    <DataTableColumnDndProvider
13
      columnOrder={columnOrder}
14
      onColumnOrderChange={setColumnOrder}
15
    >
16
      <DataTable>
17
        <DataTableDndHeader />
18
        <DataTableDndColumnBody />
19
      </DataTable>
20
    </DataTableColumnDndProvider>
21
  </DataTableRoot>
22
)

Two Reorder Surfaces, One State

DataTableViewDndMenu is a drag-to-reorder variant of the View menu that shares the same columnOrder state as the column-header drag. Users get two ways to reorder, and visibility toggles + a Reset live in the same dropdown:

1
<DataTableToolbarSection className="justify-between">
2
  <DataTableSearchFilter placeholder="Search employees..." />
3
  <DataTableViewDndMenu
4
    columnOrder={columnOrder}
5
    onColumnOrderChange={setColumnOrder}
6
    onReset={() => setColumnOrder(initialColumnOrder)}
7
  />
8
</DataTableToolbarSection>

Use DataTableViewMenu (no DnD) instead if you don’t need drag-to-reorder — it skips the @dnd-kit/* bundle.

Key Points

Every column needs an explicit id field for column order tracking
columnOrder state must be passed to both DataTableRoot and DataTableColumnDndProvider — and DataTableViewDndMenu if you use it
Headers are draggable by default — grab any header to reorder
Safe to combine with sorting and filtering — column order is independent of data order, unlike Row DnD
DataTableViewDndMenu and the column-header drag share state, so both surfaces stay in lockstep

When to Use

✅ Use Column DnD when:

Users want to customize their table layout
Different users prefer different column arrangements
Building configurable dashboards

❌ Consider other options when:

Column order is fixed by design
Tables have very few columns

Next Steps

Row DnD Table — Drag-and-drop row reordering
Virtualization Table — Virtual scrolling for large datasets
Column Pinning Table — Pin columns to edges

Column DnD Table

Overview

Virtualized Column DnD

Introduction

Installation

Basic Column DnD

Two Reorder Surfaces, One State

Key Points

When to Use

Next Steps

Getting Started

Niko Table

Examples

Contributing