1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
# Client Table Components
A set of reusable, virtualized table components for client-side data rendering, built on top of `@tanstack/react-table` and `@tanstack/react-virtual`.
## Features
- **Virtualization**: Efficiently renders large datasets (50,000+ rows) by only rendering visible rows.
- **Sorting**: Built-in column sorting (Ascending/Descending).
- **Filtering**:
- Global search (all columns).
- Column-specific filters: Text (default), Select, Boolean.
- **Pagination**: Supports both client-side and server-side (manual) pagination.
- **Column Management**:
- **Reordering**: Drag and drop columns to change order.
- **Hiding**: Right-click header to hide columns.
- **Pinning**: Right-click header to pin columns (Left/Right).
- **Excel Export**: Export current table view or custom datasets to `.xlsx`.
- **Excel Import**: Utility to parse Excel files into JSON objects.
- **Template Generation**: Create Excel templates for users to fill out and import.
## Installation / Usage
The components are located in `@/components/client-table`.
### 1. Basic Usage
```tsx
import { ClientVirtualTable, ClientTableColumnDef } from "@/components/client-table"
// 1. Define Data Type
interface User {
id: string
name: string
role: string
active: boolean
}
// 2. Define Columns
const columns: ClientTableColumnDef<User>[] = [
{
accessorKey: "name",
header: "Name",
// Default filter is text
},
{
accessorKey: "role",
header: "Role",
meta: {
filterType: "select",
filterOptions: [
{ label: "Admin", value: "admin" },
{ label: "User", value: "user" },
]
}
},
{
accessorKey: "active",
header: "Active",
meta: {
filterType: "boolean"
}
}
]
// 3. Render Component
export default function UserTable({ data }: { data: User[] }) {
return (
<ClientVirtualTable
data={data}
columns={columns}
height="600px" // Required for virtualization
enableExport={true} // Shows export button
enablePagination={true} // Shows pagination footer
/>
)
}
```
### 2. Server-Side Pagination
For very large datasets where you don't want to fetch everything at once.
```tsx
<ClientVirtualTable
data={currentData} // Only the current page data
columns={columns}
manualPagination={true}
pageCount={totalPages}
rowCount={totalRows}
pagination={{ pageIndex, pageSize }}
onPaginationChange={setPaginationState}
enablePagination={true}
/>
```
### 3. Excel Utilities
#### Exporting Data
Automatic export is available via the `enableExport` prop. For custom export logic:
```tsx
import { exportToExcel } from "@/components/client-table"
await exportToExcel(data, columns, "my-data.xlsx")
```
#### Creating Import Templates
Generate a blank Excel file with headers for users to fill in.
```tsx
import { createExcelTemplate } from "@/components/client-table"
await createExcelTemplate({
columns,
filename: "user-import-template.xlsx",
excludeColumns: ["id", "createdAt"], // Columns to skip
includeColumns: [{ key: "notes", header: "Notes" }] // Extra columns
})
```
#### Importing Data
Parses an uploaded Excel file into a raw JSON array. Does **not** handle validation or DB insertion.
```tsx
import { importFromExcel } from "@/components/client-table"
const handleFileUpload = async (file: File) => {
const { data, errors } = await importFromExcel({
file,
columnMapping: { "Name": "name", "Role": "role" } // Optional header mapping
})
if (errors.length > 0) {
console.error(errors)
return
}
// Send `data` to your API/Service for validation and insertion
await saveUsers(data)
}
```
## Types
We use a custom column definition type to support our extended `meta` properties.
```typescript
import { ClientTableColumnDef } from "@/components/client-table"
const columns: ClientTableColumnDef<MyData>[] = [ ... ]
```
Supported `meta` properties:
- `filterType`: `"text" | "select" | "boolean"`
- `filterOptions`: `{ label: string; value: string }[]` (Required for `select`)
|
