Row DnD Table

Drag-and-drop row reordering with composable primitives.

Overview

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 {
7
  DataTableHeader,
8
  DataTableEmptyBody,
9
} from "@/components/niko-table/core/data-table-structure"
10
import { DataTableDndBody } from "@/components/niko-table/core/data-table-dnd-structure"
11
import { DataTableColumnHeader } from "@/components/niko-table/components/data-table-column-header"
12
import { DataTableColumnTitle } from "@/components/niko-table/components/data-table-column-title"
13
import {
14
  DataTableEmptyIcon,
15
  DataTableEmptyMessage,
16
  DataTableEmptyTitle,
17
  DataTableEmptyDescription,
18
} from "@/components/niko-table/components/data-table-empty-state"
19
import {
20
  DataTableRowDndProvider,
21
  DataTableRowDragHandle,
22
} from "@/components/niko-table/components/data-table-row-dnd"
23
import type { DataTableColumnDef } from "@/components/niko-table/types"
24
import { Badge } from "@/components/ui/badge"
25
import { Inbox } from "lucide-react"
26

27
// Types
28
type Task = {
29
  id: string
30
  title: string
31
  status: "todo" | "in-progress" | "done" | "cancelled"
32
  priority: "low" | "medium" | "high"
33
}
34

35
// Sample data
36
const initialData: Task[] = [
37
  {
38
    id: "TASK-001",
39
    title: "Set up project repository",
40
    status: "done",
41
    priority: "high",
42
  },
43
  {
44
    id: "TASK-002",
45
    title: "Design database schema",
46
    status: "in-progress",
47
    priority: "high",
48
  },
49
  {
50
    id: "TASK-003",
51
    title: "Implement authentication",
52
    status: "todo",
53
    priority: "medium",
54
  },
55
  {
56
    id: "TASK-004",
57
    title: "Create API endpoints",
58
    status: "todo",
59
    priority: "medium",
60
  },
61
  {
62
    id: "TASK-005",
63
    title: "Write unit tests",
64
    status: "todo",
65
    priority: "low",
66
  },
67
  {
68
    id: "TASK-006",
69
    title: "Set up CI/CD pipeline",
70
    status: "cancelled",
71
    priority: "low",
72
  },
73
  {
74
    id: "TASK-007",
75
    title: "Deploy to staging",
76
    status: "todo",
77
    priority: "medium",
78
  },
79
  {
80
    id: "TASK-008",
81
    title: "Performance optimization",
82
    status: "in-progress",
83
    priority: "high",
84
  },
85
]
86

87
// Status badge variant helper
88
const getStatusVariant = (status: Task["status"]) => {
89
  switch (status) {
90
    case "done":
91
      return "default"
92
    case "in-progress":
93
      return "secondary"
94
    case "todo":
95
      return "outline"
96
    case "cancelled":
97
      return "destructive"
98
    default:
99
      return "secondary"
100
  }
101
}
102

103
// Priority badge variant helper
104
const getPriorityVariant = (priority: Task["priority"]) => {
105
  switch (priority) {
106
    case "high":
107
      return "destructive"
108
    case "medium":
109
      return "secondary"
110
    case "low":
111
      return "outline"
112
    default:
113
      return "secondary"
114
  }
115
}
116

117
export default function RowDndExample() {
118
  const [data, setData] = React.useState(initialData)
119

120
  const columns: DataTableColumnDef<Task>[] = React.useMemo(
121
    () => [
122
      {
123
        id: "drag-handle",
124
        size: 40,
125
        header: () => null,
126
        cell: ({ row }) => <DataTableRowDragHandle rowId={row.id} />,
127
        enableSorting: false,
128
        enableHiding: false,
129
      },
130
      {
131
        id: "order",
132
        size: 50,
133
        header: () => (
134
          <DataTableColumnHeader>
135
            <DataTableColumnTitle title="#" />
136
          </DataTableColumnHeader>
137
        ),
138
        cell: ({ row }) => (
139
          <span className="text-muted-foreground">{row.index + 1}</span>
140
        ),
141
        enableSorting: false,
142
        enableHiding: false,
143
      },
144
      {
145
        accessorKey: "id",
146
        header: () => (
147
          <DataTableColumnHeader>
148
            <DataTableColumnTitle title="Task ID" />
149
          </DataTableColumnHeader>
150
        ),
151
        meta: { label: "Task ID" },
152
        size: 110,
153
      },
154
      {
155
        accessorKey: "title",
156
        header: () => (
157
          <DataTableColumnHeader>
158
            <DataTableColumnTitle title="Title" />
159
          </DataTableColumnHeader>
160
        ),
161
        meta: { label: "Title" },
162
      },
163
      {
164
        accessorKey: "status",
165
        header: () => (
166
          <DataTableColumnHeader>
167
            <DataTableColumnTitle title="Status" />
168
          </DataTableColumnHeader>
169
        ),
170
        meta: { label: "Status" },
171
        size: 130,
172
        cell: ({ row }) => {
173
          const status = row.getValue("status") as Task["status"]
174
          return <Badge variant={getStatusVariant(status)}>{status}</Badge>
175
        },
176
      },
177
      {
178
        accessorKey: "priority",
179
        header: () => (
180
          <DataTableColumnHeader>
181
            <DataTableColumnTitle title="Priority" />
182
          </DataTableColumnHeader>
183
        ),
184
        meta: { label: "Priority" },
185
        size: 110,
186
        cell: ({ row }) => {
187
          const priority = row.getValue("priority") as Task["priority"]
188
          return (
189
            <Badge variant={getPriorityVariant(priority)}>{priority}</Badge>
190
          )
191
        },
192
      },
193
    ],
194
    [],
195
  )
196

197
  return (
198
    <DataTableRoot data={data} columns={columns} getRowId={row => row.id}>
199
      <DataTableRowDndProvider data={data} onReorder={setData}>
200
        <DataTable>
201
          <DataTableHeader />
202
          <DataTableDndBody>
203
            <DataTableEmptyBody>
204
              <DataTableEmptyMessage>
205
                <DataTableEmptyIcon>
206
                  <Inbox className="size-12" />
207
                </DataTableEmptyIcon>
208
                <DataTableEmptyTitle>No tasks found</DataTableEmptyTitle>
209
                <DataTableEmptyDescription>
210
                  There are no tasks to display at this time.
211
                </DataTableEmptyDescription>
212
              </DataTableEmptyMessage>
213
            </DataTableEmptyBody>
214
          </DataTableDndBody>
215
        </DataTable>
216
      </DataTableRowDndProvider>
217
    </DataTableRoot>
218
  )
219
}

#	Task ID	Title	Status	Priority
1	TASK-001	Set up project repository	done	high
2	TASK-002	Design database schema	in-progress	high
3	TASK-003	Implement authentication	todo	medium
4	TASK-004	Create API endpoints	todo	medium
5	TASK-005	Write unit tests	todo	low
6	TASK-006	Set up CI/CD pipeline	cancelled	low
7	TASK-007	Deploy to staging	todo	medium
8	TASK-008	Performance optimization	in-progress	high

Preview with Controlled State

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 {
7
  DataTableHeader,
8
  DataTableEmptyBody,
9
} from "@/components/niko-table/core/data-table-structure"
10
import { DataTableDndBody } from "@/components/niko-table/core/data-table-dnd-structure"
11
import { DataTableColumnHeader } from "@/components/niko-table/components/data-table-column-header"
12
import { DataTableColumnTitle } from "@/components/niko-table/components/data-table-column-title"
13
import {
14
  DataTableEmptyIcon,
15
  DataTableEmptyMessage,
16
  DataTableEmptyTitle,
17
  DataTableEmptyDescription,
18
} from "@/components/niko-table/components/data-table-empty-state"
19
import {
20
  DataTableRowDndProvider,
21
  DataTableRowDragHandle,
22
} from "@/components/niko-table/components/data-table-row-dnd"
23
import type { DataTableColumnDef } from "@/components/niko-table/types"
24
import { Badge } from "@/components/ui/badge"
25
import { Button } from "@/components/ui/button"
26
import {
27
  Card,
28
  CardAction,
29
  CardContent,
30
  CardDescription,
31
  CardHeader,
32
  CardTitle,
33
} from "@/components/ui/card"
34
import { Inbox } from "lucide-react"
35

36
// Types
37
type Task = {
38
  id: string
39
  title: string
40
  status: "todo" | "in-progress" | "done" | "cancelled"
41
  priority: "low" | "medium" | "high"
42
}
43

44
// Sample data
45
const initialData: Task[] = [
46
  {
47
    id: "TASK-001",
48
    title: "Set up project repository",
49
    status: "done",
50
    priority: "high",
51
  },
52
  {
53
    id: "TASK-002",
54
    title: "Design database schema",
55
    status: "in-progress",
56
    priority: "high",
57
  },
58
  {
59
    id: "TASK-003",
60
    title: "Implement authentication",
61
    status: "todo",
62
    priority: "medium",
63
  },
64
  {
65
    id: "TASK-004",
66
    title: "Create API endpoints",
67
    status: "todo",
68
    priority: "medium",
69
  },
70
  {
71
    id: "TASK-005",
72
    title: "Write unit tests",
73
    status: "todo",
74
    priority: "low",
75
  },
76
  {
77
    id: "TASK-006",
78
    title: "Set up CI/CD pipeline",
79
    status: "cancelled",
80
    priority: "low",
81
  },
82
  {
83
    id: "TASK-007",
84
    title: "Deploy to staging",
85
    status: "todo",
86
    priority: "medium",
87
  },
88
  {
89
    id: "TASK-008",
90
    title: "Performance optimization",
91
    status: "in-progress",
92
    priority: "high",
93
  },
94
]
95

96
// Status badge variant helper
97
const getStatusVariant = (status: Task["status"]) => {
98
  switch (status) {
99
    case "done":
100
      return "default"
101
    case "in-progress":
102
      return "secondary"
103
    case "todo":
104
      return "outline"
105
    case "cancelled":
106
      return "destructive"
107
    default:
108
      return "secondary"
109
  }
110
}
111

112
// Priority badge variant helper
113
const getPriorityVariant = (priority: Task["priority"]) => {
114
  switch (priority) {
115
    case "high":
116
      return "destructive"
117
    case "medium":
118
      return "secondary"
119
    case "low":
120
      return "outline"
121
    default:
122
      return "secondary"
123
  }
124
}
125

126
export default function RowDndStateExample() {
127
  const [data, setData] = React.useState(initialData)
128

129
  const columns: DataTableColumnDef<Task>[] = React.useMemo(
130
    () => [
131
      {
132
        id: "drag-handle",
133
        size: 40,
134
        header: () => null,
135
        cell: ({ row }) => <DataTableRowDragHandle rowId={row.id} />,
136
        enableSorting: false,
137
        enableHiding: false,
138
      },
139
      {
140
        id: "order",
141
        size: 50,
142
        header: () => (
143
          <DataTableColumnHeader>
144
            <DataTableColumnTitle title="#" />
145
          </DataTableColumnHeader>
146
        ),
147
        cell: ({ row }) => (
148
          <span className="text-muted-foreground">{row.index + 1}</span>
149
        ),
150
        enableSorting: false,
151
        enableHiding: false,
152
      },
153
      {
154
        accessorKey: "id",
155
        header: () => (
156
          <DataTableColumnHeader>
157
            <DataTableColumnTitle title="Task ID" />
158
          </DataTableColumnHeader>
159
        ),
160
        meta: { label: "Task ID" },
161
        size: 110,
162
      },
163
      {
164
        accessorKey: "title",
165
        header: () => (
166
          <DataTableColumnHeader>
167
            <DataTableColumnTitle title="Title" />
168
          </DataTableColumnHeader>
169
        ),
170
        meta: { label: "Title" },
171
      },
172
      {
173
        accessorKey: "status",
174
        header: () => (
175
          <DataTableColumnHeader>
176
            <DataTableColumnTitle title="Status" />
177
          </DataTableColumnHeader>
178
        ),
179
        meta: { label: "Status" },
180
        size: 130,
181
        cell: ({ row }) => {
182
          const status = row.getValue("status") as Task["status"]
183
          return <Badge variant={getStatusVariant(status)}>{status}</Badge>
184
        },
185
      },
186
      {
187
        accessorKey: "priority",
188
        header: () => (
189
          <DataTableColumnHeader>
190
            <DataTableColumnTitle title="Priority" />
191
          </DataTableColumnHeader>
192
        ),
193
        meta: { label: "Priority" },
194
        size: 110,
195
        cell: ({ row }) => {
196
          const priority = row.getValue("priority") as Task["priority"]
197
          return (
198
            <Badge variant={getPriorityVariant(priority)}>{priority}</Badge>
199
          )
200
        },
201
      },
202
    ],
203
    [],
204
  )
205

206
  const resetData = () => setData(initialData)
207

208
  return (
209
    <div className="w-full space-y-4">
210
      <DataTableRoot data={data} columns={columns} getRowId={row => row.id}>
211
        <DataTableRowDndProvider data={data} onReorder={setData}>
212
          <DataTable>
213
            <DataTableHeader />
214
            <DataTableDndBody>
215
              <DataTableEmptyBody>
216
                <DataTableEmptyMessage>
217
                  <DataTableEmptyIcon>
218
                    <Inbox className="size-12" />
219
                  </DataTableEmptyIcon>
220
                  <DataTableEmptyTitle>No tasks found</DataTableEmptyTitle>
221
                  <DataTableEmptyDescription>
222
                    There are no tasks to display at this time.
223
                  </DataTableEmptyDescription>
224
                </DataTableEmptyMessage>
225
              </DataTableEmptyBody>
226
            </DataTableDndBody>
227
          </DataTable>
228
        </DataTableRowDndProvider>
229
      </DataTableRoot>
230

231
      {/* State Display */}
232
      <Card>
233
        <CardHeader>
234
          <CardTitle>Current Row Order</CardTitle>
235
          <CardDescription>
236
            Drag rows to reorder. The order is tracked in state.
237
          </CardDescription>
238
          <CardAction>
239
            <Button variant="outline" size="sm" onClick={resetData}>
240
              Reset Order
241
            </Button>
242
          </CardAction>
243
        </CardHeader>
244
        <CardContent>
245
          <div className="grid gap-2 text-xs text-muted-foreground">
246
            <div className="flex justify-between">
247
              <span className="font-medium">Total Items:</span>
248
              <span className="text-foreground">{data.length}</span>
249
            </div>
250
            <div className="flex justify-between">
251
              <span className="font-medium">Current Order:</span>
252
              <span className="text-foreground">
253
                {data.map(d => d.id).join(" → ")}
254
              </span>
255
            </div>
256
          </div>
257

258
          <details className="mt-4 border-t pt-4">
259
            <summary className="cursor-pointer text-xs font-medium hover:text-foreground">
260
              View Full State
261
            </summary>
262
            <pre className="mt-2 overflow-auto rounded bg-muted p-2 text-xs">
263
              {JSON.stringify(
264
                data.map(d => ({ id: d.id, title: d.title })),
265
                null,
266
                2,
267
              )}
268
            </pre>
269
          </details>
270
        </CardContent>
271
      </Card>
272
    </div>
273
  )
274
}

#	Task ID	Title	Status	Priority
1	TASK-001	Set up project repository	done	high
2	TASK-002	Design database schema	in-progress	high
3	TASK-003	Implement authentication	todo	medium
4	TASK-004	Create API endpoints	todo	medium
5	TASK-005	Write unit tests	todo	low
6	TASK-006	Set up CI/CD pipeline	cancelled	low
7	TASK-007	Deploy to staging	todo	medium
8	TASK-008	Performance optimization	in-progress	high

Current Row Order

Drag rows to reorder. The order is tracked in state.

Total Items:8

Current Order:TASK-001 → TASK-002 → TASK-003 → TASK-004 → TASK-005 → TASK-006 → TASK-007 → TASK-008

View Full State

[
  {
    "id": "TASK-001",
    "title": "Set up project repository"
  },
  {
    "id": "TASK-002",
    "title": "Design database schema"
  },
  {
    "id": "TASK-003",
    "title": "Implement authentication"
  },
  {
    "id": "TASK-004",
    "title": "Create API endpoints"
  },
  {
    "id": "TASK-005",
    "title": "Write unit tests"
  },
  {
    "id": "TASK-006",
    "title": "Set up CI/CD pipeline"
  },
  {
    "id": "TASK-007",
    "title": "Deploy to staging"
  },
  {
    "id": "TASK-008",
    "title": "Performance optimization"
  }
]

Virtualized Row DnD

For large datasets, use DataTableVirtualizedDndBody which combines row virtualization with drag-and-drop. Only visible rows are rendered in the DOM for optimal performance.

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 {
7
  DataTableVirtualizedFlexHeader,
8
  DataTableVirtualizedEmptyBody,
9
} from "@/components/niko-table/core/data-table-virtualized-structure"
10
import { DataTableVirtualizedDndBody } from "@/components/niko-table/core/data-table-virtualized-dnd-structure"
11
import { DataTableColumnHeader } from "@/components/niko-table/components/data-table-column-header"
12
import { DataTableColumnTitle } from "@/components/niko-table/components/data-table-column-title"
13
import {
14
  DataTableEmptyIcon,
15
  DataTableEmptyMessage,
16
  DataTableEmptyTitle,
17
  DataTableEmptyDescription,
18
} from "@/components/niko-table/components/data-table-empty-state"
19
import {
20
  DataTableRowDndProvider,
21
  DataTableRowDragHandle,
22
} from "@/components/niko-table/components/data-table-row-dnd"
23
import type { DataTableColumnDef } from "@/components/niko-table/types"
24
import { Badge } from "@/components/ui/badge"
25
import { Inbox } from "lucide-react"
26

27
// Types
28
type Task = {
29
  id: string
30
  title: string
31
  status: "todo" | "in-progress" | "done" | "cancelled"
32
  priority: "low" | "medium" | "high"
33
  assignee: string
34
}
35

36
// Generate large dataset for virtualization demo
37
const generateTasks = (count: number): Task[] => {
38
  const titles = [
39
    "Set up project repository",
40
    "Design database schema",
41
    "Implement authentication",
42
    "Create API endpoints",
43
    "Write unit tests",
44
    "Set up CI/CD pipeline",
45
    "Deploy to staging",
46
    "Performance optimization",
47
    "Code review",
48
    "Update documentation",
49
    "Fix login bug",
50
    "Add search feature",
51
    "Refactor user module",
52
    "Create dashboard",
53
    "Implement caching",
54
    "Add error handling",
55
    "Set up monitoring",
56
    "Write integration tests",
57
    "Optimize queries",
58
    "Add pagination",
59
  ]
60
  const statuses: Task["status"][] = [
61
    "todo",
62
    "in-progress",
63
    "done",
64
    "cancelled",
65
  ]
66
  const priorities: Task["priority"][] = ["low", "medium", "high"]
67
  const assignees = [
68
    "Alice",
69
    "Bob",
70
    "Carol",
71
    "David",
72
    "Eva",
73
    "Frank",
74
    "Grace",
75
    "Henry",
76
    "Ivy",
77
    "Jack",
78
  ]
79

80
  return Array.from({ length: count }, (_, i) => ({
81
    id: `TASK-${String(i + 1).padStart(4, "0")}`,
82
    title: titles[i % titles.length],
83
    status: statuses[Math.floor(Math.random() * statuses.length)],
84
    priority: priorities[Math.floor(Math.random() * priorities.length)],
85
    assignee: assignees[Math.floor(Math.random() * assignees.length)],
86
  }))
87
}
88

89
const initialData = generateTasks(500)
90

91
// Status badge variant helper
92
const getStatusVariant = (status: Task["status"]) => {
93
  switch (status) {
94
    case "done":
95
      return "default"
96
    case "in-progress":
97
      return "secondary"
98
    case "todo":
99
      return "outline"
100
    case "cancelled":
101
      return "destructive"
102
    default:
103
      return "secondary"
104
  }
105
}
106

107
// Priority badge variant helper
108
const getPriorityVariant = (priority: Task["priority"]) => {
109
  switch (priority) {
110
    case "high":
111
      return "destructive"
112
    case "medium":
113
      return "secondary"
114
    case "low":
115
      return "outline"
116
    default:
117
      return "secondary"
118
  }
119
}
120

121
export default function VirtualizedRowDndExample() {
122
  const [data, setData] = React.useState(initialData)
123

124
  const columns: DataTableColumnDef<Task>[] = React.useMemo(
125
    () => [
126
      {
127
        id: "drag-handle",
128
        size: 40,
129
        header: () => null,
130
        cell: ({ row }) => <DataTableRowDragHandle rowId={row.id} />,
131
        enableSorting: false,
132
        enableHiding: false,
133
      },
134
      {
135
        id: "order",
136
        size: 50,
137
        header: () => (
138
          <DataTableColumnHeader>
139
            <DataTableColumnTitle title="#" />
140
          </DataTableColumnHeader>
141
        ),
142
        cell: ({ row }) => (
143
          <span className="text-muted-foreground">{row.index + 1}</span>
144
        ),
145
        enableSorting: false,
146
        enableHiding: false,
147
      },
148
      {
149
        accessorKey: "id",
150
        header: () => (
151
          <DataTableColumnHeader>
152
            <DataTableColumnTitle title="Task ID" />
153
          </DataTableColumnHeader>
154
        ),
155
        meta: { label: "Task ID" },
156
        size: 110,
157
      },
158
      {
159
        accessorKey: "title",
160
        header: () => (
161
          <DataTableColumnHeader>
162
            <DataTableColumnTitle title="Title" />
163
          </DataTableColumnHeader>
164
        ),
165
        meta: { label: "Title" },
166
      },
167
      {
168
        accessorKey: "assignee",
169
        header: () => (
170
          <DataTableColumnHeader>
171
            <DataTableColumnTitle title="Assignee" />
172
          </DataTableColumnHeader>
173
        ),
174
        meta: { label: "Assignee" },
175
        size: 120,
176
      },
177
      {
178
        accessorKey: "status",
179
        header: () => (
180
          <DataTableColumnHeader>
181
            <DataTableColumnTitle title="Status" />
182
          </DataTableColumnHeader>
183
        ),
184
        meta: { label: "Status" },
185
        size: 130,
186
        cell: ({ row }) => {
187
          const status = row.getValue("status") as Task["status"]
188
          return <Badge variant={getStatusVariant(status)}>{status}</Badge>
189
        },
190
      },
191
      {
192
        accessorKey: "priority",
193
        header: () => (
194
          <DataTableColumnHeader>
195
            <DataTableColumnTitle title="Priority" />
196
          </DataTableColumnHeader>
197
        ),
198
        meta: { label: "Priority" },
199
        size: 110,
200
        cell: ({ row }) => {
201
          const priority = row.getValue("priority") as Task["priority"]
202
          return (
203
            <Badge variant={getPriorityVariant(priority)}>{priority}</Badge>
204
          )
205
        },
206
      },
207
    ],
208
    [],
209
  )
210

211
  return (
212
    <DataTableRoot data={data} columns={columns} getRowId={row => row.id}>
213
      <DataTableRowDndProvider data={data} onReorder={setData}>
214
        <DataTable height={500}>
215
          <DataTableVirtualizedFlexHeader />
216
          <DataTableVirtualizedDndBody estimateSize={40} overscan={10}>
217
            <DataTableVirtualizedEmptyBody>
218
              <DataTableEmptyMessage>
219
                <DataTableEmptyIcon>
220
                  <Inbox className="size-12" />
221
                </DataTableEmptyIcon>
222
                <DataTableEmptyTitle>No tasks found</DataTableEmptyTitle>
223
                <DataTableEmptyDescription>
224
                  There are no tasks to display at this time.
225
                </DataTableEmptyDescription>
226
              </DataTableEmptyMessage>
227
            </DataTableVirtualizedEmptyBody>
228
          </DataTableVirtualizedDndBody>
229
        </DataTable>
230
      </DataTableRowDndProvider>
231
    </DataTableRoot>
232
  )
233
}

Introduction

Row DnD lets users reorder table rows by dragging. Built with @dnd-kit and composable primitives that follow the shadcn/ui open-code pattern — copy the code, modify freely.

Installation

Install the DataTable core and row DnD add-on:

pnpm dlx shadcn@latest add @niko-table/data-table @niko-table/data-table-row-dnd

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.

Prerequisites

We’ll build a task board with draggable rows:

1
type Task = {
2
  id: string
3
  title: string
4
  status: "todo" | "in-progress" | "done" | "cancelled"
5
  priority: "low" | "medium" | "high"
6
}

Basic Row DnD

Three components work together:

DataTableRowDndProvider — Wraps the table with DnD context and sensors
DataTableDndBody — Renders rows as draggable items
DataTableRowDragHandle — A grip icon button for dragging

1
const [data, setData] = React.useState(initialData)
2

3
const columns: DataTableColumnDef<Task>[] = [
4
  {
5
    id: "drag-handle",
6
    size: 40,
7
    header: () => null,
8
    cell: ({ row }) => <DataTableRowDragHandle rowId={row.id} />,
9
    enableSorting: false,
10
    enableHiding: false,
11
  },
12
  // ... other columns
13
]
14

15
return (
16
  <DataTableRoot data={data} columns={columns} getRowId={(row) => row.id}>
17
    <DataTableRowDndProvider data={data} onReorder={setData}>
18
      <DataTable>
19
        <DataTableHeader />
20
        <DataTableDndBody />
21
      </DataTable>
22
    </DataTableRowDndProvider>
23
  </DataTableRoot>
24
)

Key Points

getRowId is required — use stable, unique IDs (e.g., database IDs), not array indexes. Array indexes break DnD after reordering because the index no longer matches the original item
DataTableRowDndProvider must wrap outside <DataTable> — DnD context creates <div> elements that can’t be inside <table>
onReorder receives the new data array after arrayMove — just pass setData

Drag Handle Column

The drag handle is a dedicated column with DataTableRowDragHandle:

1
{
2
  id: "drag-handle",
3
  size: 40,
4
  header: () => null,
5
  cell: ({ row }) => <DataTableRowDragHandle rowId={row.id} />,
6
  enableSorting: false,
7
  enableHiding: false,
8
}

Controlled State

Track the data order externally:

1
const [data, setData] = React.useState(initialData)
2

3
// Reset to original order
4
const resetData = () => setData(initialData)
5

6
return (
7
  <DataTableRoot data={data} columns={columns} getRowId={(row) => row.id}>
8
    <DataTableRowDndProvider data={data} onReorder={setData}>
9
      <DataTable>
10
        <DataTableHeader />
11
        <DataTableDndBody />
12
      </DataTable>
13
    </DataTableRowDndProvider>
14
  </DataTableRoot>
15
)

Best Practices

Don’t combine sorting or filtering with row DnD. Sorting and filtering override the manual row order — if a user drags row 3 to position 1, then a sort or filter resets it, the reorder is lost.

Avoid DataTableColumnSortMenu, DataTableSearchFilter, and DataTableFacetedFilter in DnD tables
If you need search, consider filtering the source data before passing it to the table
Column DnD is safe to combine with sorting/filtering since column order is independent of data order

When to Use

✅ Use Row DnD when:

Users need to manually prioritize or reorder items
Building kanban boards, task lists, or playlist managers
Order matters and should be persisted

❌ Consider other options when:

Data has a natural sort order (use sorting instead)
The table is read-only and order doesn’t matter

Next Steps

Column DnD Table — Drag-and-drop column reordering
Row Selection Table — Combine with row selection