@kanunilabs/datagrid-react 1.0.2 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +247 -246
- package/dist/index.cjs +2 -2
- package/dist/index.d.cts +5 -134
- package/dist/index.d.ts +5 -134
- package/dist/index.js +2 -2
- package/dist/styles.css +2380 -2351
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -1,246 +1,247 @@
|
|
|
1
|
-
<p align="center">
|
|
2
|
-
<a href="https://www.kanunilabs.com"><img src="https://www.kanunilabs.com/logo.png" width="84" alt="KanuniLabs" /></a>
|
|
3
|
-
</p>
|
|
4
|
-
|
|
5
|
-
<h1 align="center">KanuniLabs DataGrid for React</h1>
|
|
6
|
-
|
|
7
|
-
<p align="center">
|
|
8
|
-
A high-performance React data grid with a Web Worker pipeline —<br />
|
|
9
|
-
sort, filter and scroll a million rows without freezing the UI.
|
|
10
|
-
</p>
|
|
11
|
-
|
|
12
|
-
<p align="center">
|
|
13
|
-
<a href="https://www.kanunilabs.com">Website</a> ·
|
|
14
|
-
<a href="https://www.kanunilabs.com/playground/datagrid">Live Demo</a> ·
|
|
15
|
-
<a href="https://www.kanunilabs.com/docs/datagrid">Documentation</a> ·
|
|
16
|
-
<a href="https://www.kanunilabs.com/pricing">Pricing</a> ·
|
|
17
|
-
<a href="https://www.kanunilabs.com/contact">Support</a>
|
|
18
|
-
</p>
|
|
19
|
-
|
|
20
|
-
<p align="center">
|
|
21
|
-
<a href="https://www.npmjs.com/package/@kanunilabs/datagrid-react"><img src="https://img.shields.io/npm/v/%40kanunilabs%2Fdatagrid-react.svg?label=npm" alt="npm version" /></a>
|
|
22
|
-
<img src="https://img.shields.io/badge/TypeScript-included-3178c6.svg" alt="TypeScript types included" />
|
|
23
|
-
<img src="https://img.shields.io/badge/dependencies-react%20only-2ea44f.svg" alt="No runtime dependencies beyond React" />
|
|
24
|
-
<img src="https://img.shields.io/badge/license-Community%20(free)-2ea44f.svg" alt="KanuniLabs Community License" />
|
|
25
|
-
</p>
|
|
26
|
-
|
|
27
|
-
<p align="center">
|
|
28
|
-
<a href="https://www.kanunilabs.com/playground/datagrid">
|
|
29
|
-
<img src="https://www.kanunilabs.com/npm/datagrid-react.gif" alt="KanuniLabs DataGrid for React in action — scrolling, filtering and editing a million rows with banded headers, sparklines and column-aligned totals" width="100%" />
|
|
30
|
-
</a>
|
|
31
|
-
</p>
|
|
32
|
-
|
|
33
|
-
<p align="center">
|
|
34
|
-
<a href="https://www.kanunilabs.com/playground/datagrid">Try it live</a> — a million rows in your browser. No signup, no install.
|
|
35
|
-
</p>
|
|
36
|
-
|
|
37
|
-
## Why KanuniLabs DataGrid?
|
|
38
|
-
|
|
39
|
-
- **Worker-backed pipeline** — above ~20,000 rows, filtering and sorting move off the main thread automatically. Columns are encoded once into typed arrays and transferred (zero-copy); a later sort or filter reuses them instead of re-encoding.
|
|
40
|
-
- **Measured, not claimed** — at **1,000,000 rows** on one machine: numeric sort **90 ms**, text sort **108 ms**, two-column sort **192 ms**, equality filter **19 ms**, free-text search **58 ms**. Reproduce it yourself with the bench in the repo; the [performance notes](https://www.kanunilabs.com/docs/datagrid/performance) explain the technique behind each number.
|
|
41
|
-
- **Row _and_ column virtualization** — only the visible window is in the DOM. A 100,000-row grid keeps ~25 rows mounted; columns scrolled out of view are replaced by a spacer, not rendered.
|
|
42
|
-
- **Local or server-side** — hand it an array and everything runs in the browser, or implement a `DataSource` and filtering, sorting, paging, distinct values and totals all execute on your server while the grid stays the same component. (The server-side model is [Enterprise](#enterprise-edition).)
|
|
43
|
-
- **Pinned columns that cannot drift** — pinned columns are sticky cells inside a *single* scroll container. There is no second table to keep in sync, so the header and body cannot fall out of alignment.
|
|
44
|
-
- **Sorting & filtering** — multi-column sort, a per-column filter row with operator prefixes (`>=100`), and an Excel-style header filter popup with a searchable value list.
|
|
45
|
-
- **Grouping** — group by a column with expand/collapse and counts; drag columns into the group panel to regroup. (Nested grouping
|
|
46
|
-
- **Selection & keyboard** — row selection keyed by row identity, so it survives sorting and filtering. Full WAI-ARIA grid keyboard model: arrows, <kbd>Page↑/↓</kbd>, <kbd>Home</kbd>/<kbd>End</kbd>, <kbd>Space</kbd> to toggle, <kbd>Shift</kbd>+arrows to extend, <kbd>Ctrl</kbd>+<kbd>A</kbd>, <kbd>Ctrl</kbd>+<kbd>C</kbd>.
|
|
47
|
-
- **CSV export & import** — RFC 4180 with a UTF-8 BOM so Excel opens it correctly; import sniffs the delimiter and infers types. (Excel and PDF export are [Enterprise](#enterprise-edition).)
|
|
48
|
-
- **Accessible** — `role="grid"` with `aria-rowindex`/`aria-colindex`, virtual focus via `aria-activedescendant`, live-region announcements, and a single tab stop for the whole header.
|
|
49
|
-
- **TypeScript-first & dependency-free** — complete type definitions; React is the only runtime peer.
|
|
50
|
-
|
|
51
|
-
## Quick start
|
|
52
|
-
|
|
53
|
-
```bash
|
|
54
|
-
npm install @kanunilabs/datagrid-react
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
`@kanunilabs/datagrid-core` (the engine) is installed automatically.
|
|
58
|
-
|
|
59
|
-
```tsx
|
|
60
|
-
import { DataGrid, type ReactGridColumnDef } from '@kanunilabs/datagrid-react';
|
|
61
|
-
import '@kanunilabs/datagrid-react/styles.css';
|
|
62
|
-
|
|
63
|
-
interface Sale {
|
|
64
|
-
id: number;
|
|
65
|
-
product: string;
|
|
66
|
-
region: string;
|
|
67
|
-
revenue: number;
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
const columns: ReactGridColumnDef<Sale>[] = [
|
|
71
|
-
{ field: 'id', headerName: 'ID', dataType: 'number', width: 80, pin: 'left' },
|
|
72
|
-
{ field: 'product', headerName: 'Product', width: 220 },
|
|
73
|
-
{ field: 'region', headerName: 'Region', width: 140 },
|
|
74
|
-
{
|
|
75
|
-
field: 'revenue',
|
|
76
|
-
headerName: 'Revenue',
|
|
77
|
-
dataType: 'number',
|
|
78
|
-
width: 140,
|
|
79
|
-
valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
|
|
80
|
-
},
|
|
81
|
-
];
|
|
82
|
-
|
|
83
|
-
export default function App() {
|
|
84
|
-
return (
|
|
85
|
-
<DataGrid<Sale>
|
|
86
|
-
gridId="sales"
|
|
87
|
-
dataSource={rows}
|
|
88
|
-
rowKey="id"
|
|
89
|
-
columns={columns}
|
|
90
|
-
selection={{ mode: 'multiple', checkboxColumn: true }}
|
|
91
|
-
sorting={{ multi: true }}
|
|
92
|
-
filterRow
|
|
93
|
-
headerFilter
|
|
94
|
-
toolbar
|
|
95
|
-
style={{ height: 600 }}
|
|
96
|
-
/>
|
|
97
|
-
);
|
|
98
|
-
}
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
`rowKey` is required: selection, focus and live updates are keyed by row identity, which is what lets them survive sorting and filtering.
|
|
102
|
-
|
|
103
|
-
## The Web Worker: nothing to configure
|
|
104
|
-
|
|
105
|
-
Filtering and sorting run off the main thread above 20,000 rows. The worker is compiled into the package and started from a Blob URL, so there is no file to copy, no bundler recipe, and nothing to import — Vite, webpack, Next.js and Parcel all just work.
|
|
106
|
-
|
|
107
|
-
Set `worker={{ enabled: false }}` to stay on the main thread entirely, or `worker={{ threshold: 50_000 }}` to change when the offload kicks in.
|
|
108
|
-
|
|
109
|
-
**Strict Content-Security-Policy.** A Blob worker needs `worker-src 'self' blob:`. If your CSP forbids it, either allow it or serve the worker as a file instead:
|
|
110
|
-
|
|
111
|
-
```tsx
|
|
112
|
-
import workerUrl from '@kanunilabs/datagrid-core/dist/datagrid.worker.js?url';
|
|
113
|
-
|
|
114
|
-
<DataGrid worker={{ url: workerUrl }} /* ... */ />
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
The same escape hatch is there if you would rather serve the worker from a CDN so it caches separately from your app bundle. `datagrid.worker.js` ships in the package either way.
|
|
118
|
-
|
|
119
|
-
## Excel export (optional)
|
|
120
|
-
|
|
121
|
-
CSV export needs nothing extra. For `.xlsx`, install the optional peer:
|
|
122
|
-
|
|
123
|
-
```bash
|
|
124
|
-
npm i exceljs
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
Without it, CSV export still works and the Excel path reports an actionable error instead of failing at import time.
|
|
128
|
-
|
|
129
|
-
## Theming
|
|
130
|
-
|
|
131
|
-
Six packaged themes, each in a light and a dark palette at three densities:
|
|
132
|
-
|
|
133
|
-
```tsx
|
|
134
|
-
<DataGrid theme="quartz" density="compact" dark={isDark} … />
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
`quartz` (minimal chrome) · `balham` (dense, fully ruled) · `material` (tall, elevated) · `alpine` (airy, framed) · `kanuni` and `kanuni-midnight` (the house themes).
|
|
138
|
-
|
|
139
|
-
**Omit `theme` and nothing changes** — the packaged look is the default, not one of the six. Switching is a class swap on the grid root, so it repaints without re-rendering a cell.
|
|
140
|
-
|
|
141
|
-
A **palette** is a second, independent axis — it changes the colours and leaves the theme's structure alone:
|
|
142
|
-
|
|
143
|
-
```tsx
|
|
144
|
-
<DataGrid theme="balham" palette="nord" … />
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
`nord` · `dracula` · `solarized` · `gruvbox` · `catppuccin` · `tokyo-night`, each in light and dark. The two multiply: Balham's dense ruled grid in Nord's arctic blues, or Material's tall airy one in the same blues.
|
|
148
|
-
|
|
149
|
-
`density` moves the whole vertical rhythm together, not just the type: row and header height, cell padding, control sizes, toolbar and pager padding.
|
|
150
|
-
|
|
151
|
-
Every colour, metric, shadow and border the stylesheet draws with is a `--dg-*` custom property, so your own theme is written the same way ours are:
|
|
152
|
-
|
|
153
|
-
```css
|
|
154
|
-
.my-grid-theme {
|
|
155
|
-
--dg-surface: #fffdf8;
|
|
156
|
-
--dg-primary: #8a6d2f;
|
|
157
|
-
--dg-on-primary: #ffffff; /* what sits ON the accent — set it, don't inherit */
|
|
158
|
-
--dg-cell-border: none; /* a whole shorthand, so a rule can be dropped */
|
|
159
|
-
}
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Full token list and the caveats (portalled popups, row height and the virtualizer) are in the [theming guide](https://www.kanunilabs.com/docs/datagrid/theming).
|
|
163
|
-
|
|
164
|
-
## Enterprise edition
|
|
165
|
-
|
|
166
|
-
Community is a complete grid: a million rows, sorting, filtering, selection,
|
|
167
|
-
pagination, grouping, themes, twelve languages and CSV export. Nothing here is
|
|
168
|
-
a trial and nothing expires.
|
|
169
|
-
|
|
170
|
-
`@kanunilabs/datagrid-react-enterprise` starts where you **change** the data and
|
|
171
|
-
where you **take it out** — editing, range selection and the fill handle,
|
|
172
|
-
server-side data, Excel and PDF export, charts. `EnterpriseDataGrid` is a
|
|
173
|
-
drop-in replacement for `DataGrid`: same props, plus those.
|
|
174
|
-
|
|
175
|
-
```bash
|
|
176
|
-
# Ships from our private registry; a license includes the credentials.
|
|
177
|
-
npm i @kanunilabs/datagrid-react-enterprise
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
```tsx
|
|
181
|
-
import { EnterpriseDataGrid, LicenseManager } from '@kanunilabs/datagrid-react-enterprise';
|
|
182
|
-
|
|
183
|
-
LicenseManager.setLicenseKey('KLAB1....');
|
|
184
|
-
|
|
185
|
-
<EnterpriseDataGrid dataSource={rows} rowKey="id" columns={columns} editing={{ mode: 'cell' }} />
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
Without a key the grid still runs — watermarked, not crippled — so an
|
|
189
|
-
evaluation or a stale staging key never takes an application down.
|
|
190
|
-
|
|
191
|
-
**One license opens both products**, DataGrid and
|
|
192
|
-
[PivotGrid](https://www.npmjs.com/package/@kanunilabs/pivotgrid-react).
|
|
193
|
-
|
|
194
|
-
- [Enterprise & licensing](https://www.kanunilabs.com/docs/datagrid/enterprise)
|
|
195
|
-
- [Private registry access](https://www.kanunilabs.com/docs/datagrid/registry)
|
|
196
|
-
- [Pricing](https://www.kanunilabs.com/pricing)
|
|
197
|
-
|
|
198
|
-
## Feature overview
|
|
199
|
-
|
|
200
|
-
| | Community (this package) | Enterprise |
|
|
201
|
-
|---|:---:|:---:|
|
|
202
|
-
| Virtualized rows + columns · 1M rows | ✅ | ✅ |
|
|
203
|
-
| Worker offload + columnar encoding | ✅ | ✅ |
|
|
204
|
-
| Sorting · resize · reorder · pinning · bands | ✅ | ✅ |
|
|
205
|
-
| Filter row · header filter popup · search | ✅ | ✅ |
|
|
206
|
-
| Row/cell selection · checkbox · focused row | ✅ | ✅ |
|
|
207
|
-
| Keyboard navigation + WAI-ARIA grid | ✅ | ✅ |
|
|
208
|
-
| Grouping (one level) + group panel | ✅ | ✅ |
|
|
209
|
-
| Pagination · infinite scroll · toolbar · column chooser | ✅ | ✅ |
|
|
210
|
-
| 6 themes × 6 palettes · dark mode · 12 locales | ✅ | ✅ |
|
|
211
|
-
|
|
|
212
|
-
| Saved views · tooltips · row numbers · print | ✅ | ✅ |
|
|
213
|
-
| **
|
|
214
|
-
| **
|
|
215
|
-
|
|
|
216
|
-
|
|
|
217
|
-
|
|
|
218
|
-
|
|
|
219
|
-
| **
|
|
220
|
-
|
|
|
221
|
-
|
|
|
222
|
-
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
- [
|
|
231
|
-
- [
|
|
232
|
-
- [
|
|
233
|
-
- [
|
|
234
|
-
- [
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://www.kanunilabs.com"><img src="https://www.kanunilabs.com/logo.png" width="84" alt="KanuniLabs" /></a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<h1 align="center">KanuniLabs DataGrid for React</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
A high-performance React data grid with a Web Worker pipeline —<br />
|
|
9
|
+
sort, filter and scroll a million rows without freezing the UI.
|
|
10
|
+
</p>
|
|
11
|
+
|
|
12
|
+
<p align="center">
|
|
13
|
+
<a href="https://www.kanunilabs.com">Website</a> ·
|
|
14
|
+
<a href="https://www.kanunilabs.com/playground/datagrid">Live Demo</a> ·
|
|
15
|
+
<a href="https://www.kanunilabs.com/docs/datagrid">Documentation</a> ·
|
|
16
|
+
<a href="https://www.kanunilabs.com/pricing">Pricing</a> ·
|
|
17
|
+
<a href="https://www.kanunilabs.com/contact">Support</a>
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
<p align="center">
|
|
21
|
+
<a href="https://www.npmjs.com/package/@kanunilabs/datagrid-react"><img src="https://img.shields.io/npm/v/%40kanunilabs%2Fdatagrid-react.svg?label=npm" alt="npm version" /></a>
|
|
22
|
+
<img src="https://img.shields.io/badge/TypeScript-included-3178c6.svg" alt="TypeScript types included" />
|
|
23
|
+
<img src="https://img.shields.io/badge/dependencies-react%20only-2ea44f.svg" alt="No runtime dependencies beyond React" />
|
|
24
|
+
<img src="https://img.shields.io/badge/license-Community%20(free)-2ea44f.svg" alt="KanuniLabs Community License" />
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
<p align="center">
|
|
28
|
+
<a href="https://www.kanunilabs.com/playground/datagrid">
|
|
29
|
+
<img src="https://www.kanunilabs.com/npm/datagrid-react.gif" alt="KanuniLabs DataGrid for React in action — scrolling, filtering and editing a million rows with banded headers, sparklines and column-aligned totals" width="100%" />
|
|
30
|
+
</a>
|
|
31
|
+
</p>
|
|
32
|
+
|
|
33
|
+
<p align="center">
|
|
34
|
+
<a href="https://www.kanunilabs.com/playground/datagrid">Try it live</a> — a million rows in your browser. No signup, no install.
|
|
35
|
+
</p>
|
|
36
|
+
|
|
37
|
+
## Why KanuniLabs DataGrid?
|
|
38
|
+
|
|
39
|
+
- **Worker-backed pipeline** — above ~20,000 rows, filtering and sorting move off the main thread automatically. Columns are encoded once into typed arrays and transferred (zero-copy); a later sort or filter reuses them instead of re-encoding.
|
|
40
|
+
- **Measured, not claimed** — at **1,000,000 rows** on one machine: numeric sort **90 ms**, text sort **108 ms**, two-column sort **192 ms**, equality filter **19 ms**, free-text search **58 ms**. Reproduce it yourself with the bench in the repo; the [performance notes](https://www.kanunilabs.com/docs/datagrid/performance) explain the technique behind each number.
|
|
41
|
+
- **Row _and_ column virtualization** — only the visible window is in the DOM. A 100,000-row grid keeps ~25 rows mounted; columns scrolled out of view are replaced by a spacer, not rendered.
|
|
42
|
+
- **Local or server-side** — hand it an array and everything runs in the browser, or implement a `DataSource` and filtering, sorting, paging, distinct values and totals all execute on your server while the grid stays the same component. (The server-side model is [Enterprise](#enterprise-edition).)
|
|
43
|
+
- **Pinned columns that cannot drift** — pinned columns are sticky cells inside a *single* scroll container. There is no second table to keep in sync, so the header and body cannot fall out of alignment.
|
|
44
|
+
- **Sorting & filtering** — multi-column sort, a per-column filter row with operator prefixes (`>=100`), and an Excel-style header filter popup with a searchable value list.
|
|
45
|
+
- **Grouping** — group by a column with expand/collapse and counts; drag columns into the group panel to regroup. (Nested grouping and per-group totals are [Enterprise](#enterprise-edition); footer column totals are free.)
|
|
46
|
+
- **Selection & keyboard** — row selection keyed by row identity, so it survives sorting and filtering. Full WAI-ARIA grid keyboard model: arrows, <kbd>Page↑/↓</kbd>, <kbd>Home</kbd>/<kbd>End</kbd>, <kbd>Space</kbd> to toggle, <kbd>Shift</kbd>+arrows to extend, <kbd>Ctrl</kbd>+<kbd>A</kbd>, <kbd>Ctrl</kbd>+<kbd>C</kbd>.
|
|
47
|
+
- **CSV export & import** — RFC 4180 with a UTF-8 BOM so Excel opens it correctly; import sniffs the delimiter and infers types. (Excel and PDF export are [Enterprise](#enterprise-edition).)
|
|
48
|
+
- **Accessible** — `role="grid"` with `aria-rowindex`/`aria-colindex`, virtual focus via `aria-activedescendant`, live-region announcements, and a single tab stop for the whole header.
|
|
49
|
+
- **TypeScript-first & dependency-free** — complete type definitions; React is the only runtime peer.
|
|
50
|
+
|
|
51
|
+
## Quick start
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npm install @kanunilabs/datagrid-react
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`@kanunilabs/datagrid-core` (the engine) is installed automatically.
|
|
58
|
+
|
|
59
|
+
```tsx
|
|
60
|
+
import { DataGrid, type ReactGridColumnDef } from '@kanunilabs/datagrid-react';
|
|
61
|
+
import '@kanunilabs/datagrid-react/styles.css';
|
|
62
|
+
|
|
63
|
+
interface Sale {
|
|
64
|
+
id: number;
|
|
65
|
+
product: string;
|
|
66
|
+
region: string;
|
|
67
|
+
revenue: number;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const columns: ReactGridColumnDef<Sale>[] = [
|
|
71
|
+
{ field: 'id', headerName: 'ID', dataType: 'number', width: 80, pin: 'left' },
|
|
72
|
+
{ field: 'product', headerName: 'Product', width: 220 },
|
|
73
|
+
{ field: 'region', headerName: 'Region', width: 140 },
|
|
74
|
+
{
|
|
75
|
+
field: 'revenue',
|
|
76
|
+
headerName: 'Revenue',
|
|
77
|
+
dataType: 'number',
|
|
78
|
+
width: 140,
|
|
79
|
+
valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
|
|
80
|
+
},
|
|
81
|
+
];
|
|
82
|
+
|
|
83
|
+
export default function App() {
|
|
84
|
+
return (
|
|
85
|
+
<DataGrid<Sale>
|
|
86
|
+
gridId="sales"
|
|
87
|
+
dataSource={rows}
|
|
88
|
+
rowKey="id"
|
|
89
|
+
columns={columns}
|
|
90
|
+
selection={{ mode: 'multiple', checkboxColumn: true }}
|
|
91
|
+
sorting={{ multi: true }}
|
|
92
|
+
filterRow
|
|
93
|
+
headerFilter
|
|
94
|
+
toolbar
|
|
95
|
+
style={{ height: 600 }}
|
|
96
|
+
/>
|
|
97
|
+
);
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`rowKey` is required: selection, focus and live updates are keyed by row identity, which is what lets them survive sorting and filtering.
|
|
102
|
+
|
|
103
|
+
## The Web Worker: nothing to configure
|
|
104
|
+
|
|
105
|
+
Filtering and sorting run off the main thread above 20,000 rows. The worker is compiled into the package and started from a Blob URL, so there is no file to copy, no bundler recipe, and nothing to import — Vite, webpack, Next.js and Parcel all just work.
|
|
106
|
+
|
|
107
|
+
Set `worker={{ enabled: false }}` to stay on the main thread entirely, or `worker={{ threshold: 50_000 }}` to change when the offload kicks in.
|
|
108
|
+
|
|
109
|
+
**Strict Content-Security-Policy.** A Blob worker needs `worker-src 'self' blob:`. If your CSP forbids it, either allow it or serve the worker as a file instead:
|
|
110
|
+
|
|
111
|
+
```tsx
|
|
112
|
+
import workerUrl from '@kanunilabs/datagrid-core/dist/datagrid.worker.js?url';
|
|
113
|
+
|
|
114
|
+
<DataGrid worker={{ url: workerUrl }} /* ... */ />
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
The same escape hatch is there if you would rather serve the worker from a CDN so it caches separately from your app bundle. `datagrid.worker.js` ships in the package either way.
|
|
118
|
+
|
|
119
|
+
## Excel export (optional)
|
|
120
|
+
|
|
121
|
+
CSV export needs nothing extra. For `.xlsx`, install the optional peer:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
npm i exceljs
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Without it, CSV export still works and the Excel path reports an actionable error instead of failing at import time.
|
|
128
|
+
|
|
129
|
+
## Theming
|
|
130
|
+
|
|
131
|
+
Six packaged themes, each in a light and a dark palette at three densities:
|
|
132
|
+
|
|
133
|
+
```tsx
|
|
134
|
+
<DataGrid theme="quartz" density="compact" dark={isDark} … />
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`quartz` (minimal chrome) · `balham` (dense, fully ruled) · `material` (tall, elevated) · `alpine` (airy, framed) · `kanuni` and `kanuni-midnight` (the house themes).
|
|
138
|
+
|
|
139
|
+
**Omit `theme` and nothing changes** — the packaged look is the default, not one of the six. Switching is a class swap on the grid root, so it repaints without re-rendering a cell.
|
|
140
|
+
|
|
141
|
+
A **palette** is a second, independent axis — it changes the colours and leaves the theme's structure alone:
|
|
142
|
+
|
|
143
|
+
```tsx
|
|
144
|
+
<DataGrid theme="balham" palette="nord" … />
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
`nord` · `dracula` · `solarized` · `gruvbox` · `catppuccin` · `tokyo-night`, each in light and dark. The two multiply: Balham's dense ruled grid in Nord's arctic blues, or Material's tall airy one in the same blues.
|
|
148
|
+
|
|
149
|
+
`density` moves the whole vertical rhythm together, not just the type: row and header height, cell padding, control sizes, toolbar and pager padding.
|
|
150
|
+
|
|
151
|
+
Every colour, metric, shadow and border the stylesheet draws with is a `--dg-*` custom property, so your own theme is written the same way ours are:
|
|
152
|
+
|
|
153
|
+
```css
|
|
154
|
+
.my-grid-theme {
|
|
155
|
+
--dg-surface: #fffdf8;
|
|
156
|
+
--dg-primary: #8a6d2f;
|
|
157
|
+
--dg-on-primary: #ffffff; /* what sits ON the accent — set it, don't inherit */
|
|
158
|
+
--dg-cell-border: none; /* a whole shorthand, so a rule can be dropped */
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Full token list and the caveats (portalled popups, row height and the virtualizer) are in the [theming guide](https://www.kanunilabs.com/docs/datagrid/theming).
|
|
163
|
+
|
|
164
|
+
## Enterprise edition
|
|
165
|
+
|
|
166
|
+
Community is a complete grid: a million rows, sorting, filtering, selection,
|
|
167
|
+
pagination, grouping, themes, twelve languages and CSV export. Nothing here is
|
|
168
|
+
a trial and nothing expires.
|
|
169
|
+
|
|
170
|
+
`@kanunilabs/datagrid-react-enterprise` starts where you **change** the data and
|
|
171
|
+
where you **take it out** — editing, range selection and the fill handle,
|
|
172
|
+
server-side data, Excel and PDF export, charts. `EnterpriseDataGrid` is a
|
|
173
|
+
drop-in replacement for `DataGrid`: same props, plus those.
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
# Ships from our private registry; a license includes the credentials.
|
|
177
|
+
npm i @kanunilabs/datagrid-react-enterprise
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
```tsx
|
|
181
|
+
import { EnterpriseDataGrid, LicenseManager } from '@kanunilabs/datagrid-react-enterprise';
|
|
182
|
+
|
|
183
|
+
LicenseManager.setLicenseKey('KLAB1....');
|
|
184
|
+
|
|
185
|
+
<EnterpriseDataGrid dataSource={rows} rowKey="id" columns={columns} editing={{ mode: 'cell' }} />
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Without a key the grid still runs — watermarked, not crippled — so an
|
|
189
|
+
evaluation or a stale staging key never takes an application down.
|
|
190
|
+
|
|
191
|
+
**One license opens both products**, DataGrid and
|
|
192
|
+
[PivotGrid](https://www.npmjs.com/package/@kanunilabs/pivotgrid-react).
|
|
193
|
+
|
|
194
|
+
- [Enterprise & licensing](https://www.kanunilabs.com/docs/datagrid/enterprise)
|
|
195
|
+
- [Private registry access](https://www.kanunilabs.com/docs/datagrid/registry)
|
|
196
|
+
- [Pricing](https://www.kanunilabs.com/pricing)
|
|
197
|
+
|
|
198
|
+
## Feature overview
|
|
199
|
+
|
|
200
|
+
| | Community (this package) | Enterprise |
|
|
201
|
+
|---|:---:|:---:|
|
|
202
|
+
| Virtualized rows + columns · 1M rows | ✅ | ✅ |
|
|
203
|
+
| Worker offload + columnar encoding | ✅ | ✅ |
|
|
204
|
+
| Sorting · resize · reorder · pinning · bands | ✅ | ✅ |
|
|
205
|
+
| Filter row · header filter popup · search | ✅ | ✅ |
|
|
206
|
+
| Row/cell selection · checkbox · focused row | ✅ | ✅ |
|
|
207
|
+
| Keyboard navigation + WAI-ARIA grid | ✅ | ✅ |
|
|
208
|
+
| Grouping (one level) + group panel | ✅ | ✅ |
|
|
209
|
+
| Pagination · infinite scroll · toolbar · column chooser | ✅ | ✅ |
|
|
210
|
+
| 6 themes × 6 palettes · dark mode · 12 locales | ✅ | ✅ |
|
|
211
|
+
| 57 events + imperative controller API | ✅ | ✅ |
|
|
212
|
+
| Saved views · tooltips · row numbers · print | ✅ | ✅ |
|
|
213
|
+
| **Footer column totals** · custom reducers · totals row placement | ✅ | ✅ |
|
|
214
|
+
| **CSV** export & import | ✅ | ✅ |
|
|
215
|
+
| **Editing** — cell, batch, row, form + validation | — | ✅ |
|
|
216
|
+
| Range selection · fill handle · cut & paste | — | ✅ |
|
|
217
|
+
| Multi-level grouping · per-group totals | — | ✅ |
|
|
218
|
+
| Master-detail · tree data | — | ✅ |
|
|
219
|
+
| **Server-side data** (filter/sort/page/totals remote) | — | ✅ |
|
|
220
|
+
| **Excel** & **PDF** export (styled, paginated) | — | ✅ |
|
|
221
|
+
| Chart panel · sparklines · cross-filter | — | ✅ |
|
|
222
|
+
| Nested filter builder · import wizard | — | ✅ |
|
|
223
|
+
| Side bar · status bar | — | ✅ |
|
|
224
|
+
|
|
225
|
+
Full breakdown, with a link to the guide for each line:
|
|
226
|
+
[Enterprise & licensing](https://www.kanunilabs.com/docs/datagrid/enterprise).
|
|
227
|
+
|
|
228
|
+
## Documentation
|
|
229
|
+
|
|
230
|
+
- [Getting started](https://www.kanunilabs.com/docs/datagrid)
|
|
231
|
+
- [Installation](https://www.kanunilabs.com/docs/datagrid/installation)
|
|
232
|
+
- [Features](https://www.kanunilabs.com/docs/datagrid/features)
|
|
233
|
+
- [Theming](https://www.kanunilabs.com/docs/datagrid/theming)
|
|
234
|
+
- [Performance](https://www.kanunilabs.com/docs/datagrid/performance)
|
|
235
|
+
- [Live playground](https://www.kanunilabs.com/playground/datagrid)
|
|
236
|
+
|
|
237
|
+
## Missing a feature? Tell us
|
|
238
|
+
|
|
239
|
+
This grid is actively developed and shaped by the people using it. If something is missing, awkward, or broken, we want to hear about it — feature requests and bug reports go to the same place and get read by the people who write the code:
|
|
240
|
+
|
|
241
|
+
**[Send us your feedback →](https://www.kanunilabs.com/contact)**
|
|
242
|
+
|
|
243
|
+
## License
|
|
244
|
+
|
|
245
|
+
Free to use under the KanuniLabs Community License (proprietary, source not distributed). See the `LICENSE` file in the package.
|
|
246
|
+
|
|
247
|
+
© KanuniLabs · [kanunilabs.com](https://www.kanunilabs.com)
|