react-gridix 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
-# react-gridix
+# react-gridix Docs
 
-A React `DataGrid` with per-column filters, in-cell editing, nested fields, themes and custom components, plus the `Checkbox` it uses.
+A React `DataGrid` with row selection, server-side mode, typed per-column filters, date columns, in-cell editing, resizing and pinning, virtualization, CSV export and 8 themes, plus the `Checkbox` it uses.
 
 **Contents**
 
@@ -11,8 +11,8 @@ A React `DataGrid` with per-column filters, in-cell editing, nested fields, them
 5. [Checkbox](#5-checkbox)
 6. [DataGrid](#6-datagrid)
 7. [Demos](#7-demos)
-8. [Development, building and publishing](#8-development-building-and-publishing)
-9. [Troubleshooting](#9-troubleshooting)
+8. [Troubleshooting](#9-troubleshooting)
+9. [Migrating from the earlier version](#10-migrating-from-the-earlier-version)
 
 ---
 
@@ -20,10 +20,29 @@ A React `DataGrid` with per-column filters, in-cell editing, nested fields, them
 
 | Component | Purpose |
 | --- | --- |
-| `DataGrid` | Data table with sorting, search, per-column filters, pagination, in-cell editing, nested fields, striping, themes and custom column components |
-| `Checkbox` | Checkbox in three looks (button with a span, tick, native), toggles with one click. The grid uses it for boolean columns, and you can use it on its own |
+| `DataGrid` | Data table with per-column sorting, search, typed per-column filters, pagination, in-cell editing, date columns, row selection, server-side mode, loading skeletons, resize / pin / hide, keyboard navigation, CSV export, virtualization, nested fields, striping, themes and custom column components |
+| `Checkbox` | Checkbox in three looks (button with a span, tick, native), toggles with one click. The grid uses it for boolean columns and row selection, and you can use it on its own |
 
-Everything is written in TypeScript, ships its own type definitions, and uses plain CSS (no CSS-in-JS runtime). The grid is 100% of its container's width by default.
+**Everything extra is opt-in.** A bare `<DataGrid columns={...} rows={...} />` is a plain read-only table. Sorting, the search box, page info, selection, resizing and the rest only appear when you switch them on:
+
+| Feature | How you switch it on | Default |
+| --- | --- | --- |
+| Sorting | `sortable: true` **on a column** | off |
+| Multi-column sort | `multiSort` on the grid | off |
+| Global search box | `searchable` | off |
+| Pagination bar (row count, page controls) | `pagination` | off |
+| Column filter | `filterable: true` on a column | off |
+| Editing | `editable` | off |
+| Row selection | `rowSelection` | off |
+| Server-side mode | `serverSide` | off |
+| Resize / pin | `resizable: true` / `pinned` on a column | off |
+| Show / hide columns button | `columnMenu` | off |
+| Arrow-key navigation | `keyboardNavigation` | off |
+| CSV export button | `exportable` | off |
+| Virtualization | `virtualize` | off |
+| Theme | `theme` | none (plain look) |
+
+Everything is written in TypeScript, ships its own type definitions, and uses plain CSS (no CSS-in-JS runtime). The grid is 100% of its container's width by default. There is deliberately **no column reordering**.
 
 ---
 
@@ -47,6 +66,32 @@ The library does not inject CSS by itself. If the grid looks unstyled, this impo
 
 ## 3. Quick start
 
+A read-only table, the smallest possible grid:
+
+```tsx
+import { DataGrid, type ColumnDef } from "react-gridix";
+import "react-gridix/style.css";
+
+interface Person { id: number; name: string; city: string }
+
+const columns: ColumnDef<Person>[] = [
+  { field: "id", headerName: "ID" },
+  { field: "name", headerName: "Name" },
+  { field: "city", headerName: "City" },
+];
+
+const rows: Person[] = [
+  { id: 1, name: "Amina", city: "Kampala" },
+  { id: 2, name: "Brian", city: "Nairobi" },
+];
+
+export default function App() {
+  return <DataGrid columns={columns} rows={rows} />;
+}
+```
+
+The same grid with the common features switched on:
+
 ```tsx
 import { useState } from "react";
 import { DataGrid, type ColumnDef } from "react-gridix";
@@ -55,20 +100,21 @@ import "react-gridix/style.css";
 interface Person {
   id: number;
   name: string;
-  contact: { email: string; phone: string };
+  joined: string; // "2026-03-14"
+  contact: { email: string };
 }
 
 const columns: ColumnDef<Person>[] = [
-  { field: "id", headerName: "ID", type: "number", editable: false },
-  { field: "name", headerName: "Name", filterable: true },
+  { field: "id", headerName: "ID", type: "number", editable: false, sortable: true },
+  { field: "name", headerName: "Name", sortable: true, filterable: true },
+  { field: "joined", headerName: "Joined", type: "date", sortable: true, filterable: true },
   { field: "contact.email", headerName: "Email" },
-  { field: "contact.phone", headerName: "Phone" },
 ];
 
 export default function App() {
   const [rows, setRows] = useState<Person[]>([
-    { id: 1, name: "Amina", contact: { email: "amina@example.com", phone: "+256 700 100 200" } },
-    { id: 2, name: "Brian", contact: { email: "brian@example.com", phone: "+256 700 100 237" } },
+    { id: 1, name: "Amina", joined: "2026-03-14", contact: { email: "amina@example.com" } },
+    { id: 2, name: "Brian", joined: "2025-11-02", contact: { email: "brian@example.com" } },
   ]);
 
   return (
@@ -78,6 +124,9 @@ export default function App() {
       getRowId={(r) => r.id}
       editable
       onRowsChange={setRows}
+      searchable          // search box
+      pagination          // row count and page controls
+      rowSelection        // checkbox column
       theme="ocean"
     />
   );
@@ -102,8 +151,39 @@ Pass a theme name to the grid. **Without a `theme` prop nothing changes**: the g
 | `"midnight"` | Dark slate, indigo accent, dark popups and inputs |
 | `"sunset"` | Warm cream, orange-to-pink gradient header, serif font, rounded corners |
 | `"forest"` | Calm greens, solid dark-green header, sharper corners |
+| `"lavender"` | Light purple, soft violet gradient header, rounded corners |
+| `"coffee"` | Warm browns and cream, serif font, rich brown header |
+| `"graphite"` | Dark neutral grey with a teal accent, flat and sharp |
+| `"aurora"` | Deep night blue with a green-to-blue-to-violet gradient header and a soft glow |
+
+A theme is only a set of CSS variables on `[data-rk-theme="name"]`, written with `:where()` (zero specificity). So you can still override any variable or any class on top of a theme. Popups (the filter popup, the column menu) are drawn in `document.body`, and the grid copies the theme attribute onto them, so they follow the theme too.
 
-A theme is only a set of CSS variables on `[data-rk-theme="name"]`, written with `:where()` (zero specificity). So you can still override any variable or any class on top of a theme. The filter popup is drawn in `document.body`, and the grid copies the theme attribute onto it, so the popup follows the theme too.
+**Switching themes at run time** is just a state change:
+
+```tsx
+const [theme, setTheme] = useState<GridTheme>("ocean");
+
+<select value={theme} onChange={(e) => setTheme(e.target.value as GridTheme)}>
+  {["ocean", "midnight", "sunset", "forest", "lavender", "coffee", "graphite", "aurora"].map((t) => (
+    <option key={t}>{t}</option>
+  ))}
+</select>
+<DataGrid theme={theme} ... />
+```
+
+**Following the system dark mode.** Choose the theme from a media query:
+
+```tsx
+const dark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+<DataGrid theme={dark ? "graphite" : "lavender"} ... />
+```
+
+**Tweaking a built-in theme.** Because themes have zero specificity, any variable or rule you write wins over them:
+
+```css
+/* make the aurora header a single colour */
+[data-rk-theme="aurora"] { --rk-header-bg: #0f766e; }
+```
 
 **Making your own theme.** Any other string works as a theme name. Define the variables you want:
 
@@ -112,6 +192,7 @@ A theme is only a set of CSS variables on `[data-rk-theme="name"]`, written with
   --rk-header-bg: #7c3aed;
   --rk-header-text: #fff;
   --rk-row-hover: #f5f3ff;
+  --rk-selected-bg: #ede9fe;     /* selected rows */
   --rk-primary: #7c3aed;
 }
 ```
@@ -120,6 +201,8 @@ A theme is only a set of CSS variables on `[data-rk-theme="name"]`, written with
 <DataGrid theme="brand" ... />
 ```
 
+A dark custom theme should also set the colours that the light defaults assume, for example `--rk-surface`, `--rk-text`, `--rk-border`, `--rk-pinned-bg`, `--rk-skeleton-a` and `--rk-skeleton-b`. Copy the `graphite` block in `themes.css` as a starting point.
+
 ### 4.2 CSS variables
 
 Every variable is optional and is read with a fallback, so nothing is declared on the grid itself. Set them on `:root`, on any parent element, in your own theme, or in the grid's `style`.
@@ -139,20 +222,24 @@ Every variable is optional and is read with a fallback, so nothing is declared o
 | `--rk-grid-radius` | `10px` | Grid corner radius |
 | `--rk-grid-shadow` | `none` | Grid shadow |
 | `--rk-toolbar-bg` | `transparent` | Toolbar background |
-| `--rk-input-bg`, `--rk-input-border`, `--rk-input-text` | surface, border, inherit | Search box, filter box, editor, page controls |
+| `--rk-input-bg`, `--rk-input-border`, `--rk-input-text` | surface, border, inherit | Search box, filter inputs, editor, page controls |
 | `--rk-header-bg` | `--rk-bg-subtle` | Header background. Any CSS background, so gradients work |
 | `--rk-header-text` | inherit | Header text colour |
 | `--rk-header-hover-bg` | `rgba(0,0,0,.06)` | Header hover |
 | `--rk-header-border` | `--rk-border` | Line under the header |
 | `--rk-cell-border` | `#eef0f3` | Lines between rows |
 | `--rk-row-hover` | `#f3f4f6` | Row hover |
+| `--rk-selected-bg` | `#eef2ff` | Background of selected rows |
+| `--rk-pinned-bg` | `--rk-grid-bg` | Opaque background behind pinned body cells (so scrolled cells do not show through) |
+| `--rk-pinned-header-bg` | `--rk-bg-subtle` | Opaque background behind pinned header cells |
+| `--rk-skeleton-a`, `--rk-skeleton-b` | `#e5e7eb`, `#f3f4f6` | The two colours of the shimmering loading bars |
 | `--rk-stripe-a`, `--rk-stripe-b` | `transparent`, `#fafafa` | Alternating row colours (see [stripes](#striped-rows)) |
 | `--rk-footer-bg`, `--rk-footer-text` | subtle, muted | Pagination bar |
-| `--rk-btn-hover` | `#e5e7eb` | Page button and Clear button hover |
+| `--rk-btn-hover` | `#e5e7eb` | Page button, toolbar button and Clear button hover |
 | `--rk-filter-active` | `--rk-primary` | Filter dot colour while a filter is set |
 | `--rk-filter-glow` | `rgba(79,70,229,.25)` | Ring around an active filter dot |
-| `--rk-popup-bg`, `--rk-popup-text`, `--rk-popup-border` | white, dark, grey | Filter popup |
-| `--rk-popup-radius`, `--rk-popup-shadow` | `10px`, soft shadow | Filter popup shape |
+| `--rk-popup-bg`, `--rk-popup-text`, `--rk-popup-border` | white, dark, grey | Filter popup and column menu |
+| `--rk-popup-radius`, `--rk-popup-shadow` | `10px`, soft shadow | Popup shape |
 | `--rk-row-duration` | `0.38s` | Row entrance animation length |
 | `--rk-row-stagger` | `28ms` | Extra delay per row in the entrance animation |
 | `--rk-checkbox-size` | `20px` | Checkbox width and height |
@@ -167,9 +254,16 @@ Every variable is optional and is read with a fallback, so nothing is declared o
 :root {
   --rk-primary: #0d9488;
   --rk-row-hover: #f0fdfa;
+  --rk-selected-bg: #ccfbf1;
 }
 ```
 
+Scoped to one grid through its `style` prop:
+
+```tsx
+<DataGrid style={{ "--rk-header-bg": "#0f172a", "--rk-header-text": "#fff" } as React.CSSProperties} ... />
+```
+
 ---
 
 ## 5. Checkbox
@@ -238,8 +332,6 @@ The checkbox CSS is written with `:where()` (zero specificity), so any class you
 
 ---
 
----
-
 ## 6. DataGrid
 
 ### 6.1 Concepts
@@ -250,44 +342,104 @@ The checkbox CSS is written with `:where()` (zero specificity), so any class you
 
 - **`rows`** is an array of plain objects.
 - **`columns`** is an array of column definitions. Each one names a `field` (a key of the row object) and describes how to show, sort, filter and edit it.
-- **Row ids.** Pass `getRowId` when your rows have a stable id. Without it the grid uses each row's index in `rows`, which is fine for static data.
+- **Row ids.** Pass `getRowId` when your rows have a stable id. Without it the grid uses each row's index in `rows`, which is fine for static data. Selection, server mode and virtualization all work best with real ids.
 - **`rowIndex`** in callbacks and params is always the row's index in your original `rows` array, not its position on screen.
-- **The grid keeps its own copy of the rows** so edits appear immediately. It re-syncs whenever the `rows` prop changes identity. See [section 6.8](#68-editing).
+- **The grid keeps its own copy of the rows** so edits appear immediately. It re-syncs whenever the `rows` prop changes identity. See [section 6.9](#69-editing).
+- **Controlled or uncontrolled.** Search, filters, sort, page and selection each work two ways. Leave the prop out and the grid keeps the state itself (optionally starting from a `default…` value). Pass the prop together with its `on…Change` callback and you own the state. See [6.14](#614-controlled-state).
+- **Opt-in everywhere.** Features are off until you switch them on (see the table in the [overview](#1-overview)).
 
-The grid is generic: `DataGrid<T>` infers `T` from `rows`, and `ColumnDef<T>` checks that each `field` is a real key of `T` or a dot path into a nested object (see [nested fields](#611-nested-fields)).
+The grid is generic: `DataGrid<T>` infers `T` from `rows`, and `ColumnDef<T>` checks that each `field` is a real key of `T` or a dot path into a nested object (see [nested fields](#612-nested-fields)).
 
 ### 6.2 DataGrid props
 
+**Data and editing**
+
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `columns` | `ColumnDef<T>[]` | required | Column definitions |
-| `rows` | `T[]` | required | Data |
+| `rows` | `T[]` | required | Data. In `serverSide` mode: the current page |
 | `getRowId` | `(row, index) => string \| number` | row index | Stable id for each row |
 | `editable` | `boolean` | `false` | Allow editing cells. Columns can override this |
 | `enterMovesDown` | `boolean` | `true` | After Enter saves a cell, edit the cell below |
 | `onCellEdit` | `(event: CellEditEvent<T>) => void` | | Called after a cell edit is saved |
 | `onRowsChange` | `(rows: T[]) => void` | | Called with the full updated array after an edit |
-| `sortable` | `boolean` | `true` | Click headers to sort. Columns can override |
-| `defaultSort` | `SortModel \| null` | `null` | Initial sort. Read once, on mount |
-| `onSortChange` | `(sort: SortModel \| null) => void` | | Called when the sort changes |
-| `searchable` | `boolean` | `true` | Show the global search box |
-| `searchPlaceholder` | `string` | `"Search…"` | Placeholder of the search box |
-| `pagination` | `boolean` | `true` | Split rows into pages |
-| `paginationPosition` | `"bottom" \| "top" \| "both"` | `"bottom"` | Where the row count and page controls go |
-| `pageSize` | `number` | `10` | Initial rows per page. Read once, on mount |
-| `pageSizeOptions` | `number[]` | `[5, 10, 25, 50]` | Choices in the page size menu. The current page size is added if missing |
 | `onRowClick` | `(row, rowIndex) => void` | | Called when a row is clicked |
+
+**Row selection** (see [6.13](#613-row-selection))
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `rowSelection` | `boolean \| "single" \| "multiple"` | `false` | Adds a checkbox column. `true` means `"multiple"` |
+| `selectedRowIds` | `(string \| number)[]` | | Controlled selection |
+| `defaultSelectedRowIds` | `(string \| number)[]` | `[]` | Initial selection when not controlled |
+| `onSelectionChange` | `(selection: RowSelection<T>) => void` | | Called with `{ ids, rows }` |
+| `isRowSelectable` | `(row) => boolean` | all rows | Return `false` to disable a row's checkbox |
+
+**Sorting** (see [6.4](#64-sorting))
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `multiSort` | `boolean` | `false` | Shift+click adds more sort columns |
+| `sort` | `SortModel[]` | | Controlled sort |
+| `defaultSort` | `SortModel \| SortModel[] \| null` | `null` | Initial sort when not controlled |
+| `onSortChange` | `(sort: SortModel[]) => void` | | Called when the sort changes |
+
+**Search, filters and paging** (see [6.5](#65-searching-and-filtering), [6.7](#67-pagination), [6.14](#614-controlled-state))
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `searchable` | `boolean` | `false` | Show the global search box |
+| `searchPlaceholder` | `string` | `"Search…"` | Placeholder of the search box |
+| `search` / `onSearchChange` | `string` / `(s) => void` | | Controlled search text |
+| `filters` / `onFiltersChange` | `Record<string, FilterValue>` / `(f) => void` | | Controlled column filters |
+| `pagination` | `boolean` | `false` | Split rows into pages and show the bar with the row count and page controls |
+| `paginationPosition` | `"bottom" \| "top" \| "both"` | `"bottom"` | Where the bar goes |
+| `pageSize` | `number` | `10` | Rows per page (initial value) |
+| `pageSizeOptions` | `number[]` | `[5, 10, 25, 50]` | Choices in the page size menu. The current size is added if missing |
+| `page` / `onPageChange` | `number` / `(page) => void` | | Controlled page (zero-based) |
+| `onPageSizeChange` | `(pageSize) => void` | | Called when the page size menu changes |
+
+**Server-side mode, loading and errors** (see [6.15](#615-server-side-mode), [6.16](#616-loading-skeleton))
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `serverSide` | `boolean` | `false` | Your server sorts, filters, searches and pages |
+| `rowCount` | `number` | | Total rows on the server (for the page count) |
+| `onQueryChange` | `(query: GridQuery) => void \| Promise<unknown>` | | Called on mount and whenever the query changes. A returned promise drives the loading state |
+| `queryDebounce` | `number` | `250` | Milliseconds to wait after the last keystroke before querying |
+| `loading` | `boolean` | follows the promise | Force the loading state on or off |
+| `loadingRows` | `number` | page size (max 20), or 5 | How many skeleton rows to draw |
+| `skeletonRow` | `ComponentType<SkeletonRowProps<T>>` | shimmer bars | Your own component for each placeholder row |
+| `errorMessage` | `ReactNode` | `"Could not load the data."` | Shown with a Retry button when the promise rejects |
+
+**Columns, keyboard, big data and export**
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `columnMenu` | `boolean` | `false` | A "Columns" button to show and hide columns |
+| `onColumnVisibilityChange` | `(hiddenFields: string[]) => void` | | Called with the fields that are hidden |
+| `keyboardNavigation` | `boolean` | `false` | Arrow keys, Home, End, Page Up and Page Down move between cells |
+| `virtualize` | `boolean` | `false` | Render only the visible rows |
+| `rowHeight` | `number` | `40` | Row height in px when virtualizing |
+| `overscan` | `number` | `6` | Extra rows drawn above and below the window |
+| `exportable` | `boolean \| ExportOptions` | `false` | Show an "Export CSV" button |
+| `apiRef` | `MutableRefObject<DataGridApi<T> \| null>` | | Call `exportCsv()`, `getSelectedRows()` and more from outside |
+
+**Look and feel**
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `theme` | `GridTheme \| string` | | Applies a theme. Nothing changes without it. See [Theming](#4-theming) |
 | `toolbar` | `ReactNode` | | Extra content on the right of the toolbar |
 | `emptyMessage` | `ReactNode` | `"No rows to show"` | Shown when no rows match |
 | `striped` | `boolean` | `false` | Alternate row shading |
 | `stripeColors` | `[string, string]` | | Two colours for the alternating rows. Implies `striped`. See [striped rows](#striped-rows) |
 | `animateRows` | `boolean` | `true` | Rows slide up and fade in when they render. See [row animation](#row-animation) |
-| `theme` | `"ocean" \| "midnight" \| "sunset" \| "forest" \| string` | | Applies a theme. Nothing changes without it. See [Theming](#4-theming) |
-| `checkboxVariant` | `"button" \| "tick" \| "native"` | `"native"` | Checkbox look for `type: "boolean"` columns. Columns can override it. See [Checkbox columns](#checkbox-columns-type-boolean) |
+| `checkboxVariant` | `"button" \| "tick" \| "native"` | `"native"` | Checkbox look for boolean columns and row selection. Columns can override it |
 | `maxHeight` | `number \| string` | | Makes the body scroll, with a sticky header. Example: `400` or `"60vh"` |
 | `className` | `string` | | Classes for the root element (Tailwind works). The grid is `width: 100%` of its container by default |
 | `style` | `CSSProperties` | | Inline styles for the root element |
-| `classNames` | `Partial<Record<GridSlot, string>>` | | Classes for individual parts. See [6.10](#610-styling) |
+| `classNames` | `Partial<Record<GridSlot, string>>` | | Classes for individual parts. See [6.11](#611-styling) |
 | `styles` | `Partial<Record<GridSlot, CSSProperties>>` | | Inline styles for individual parts |
 | `rowClassName` | `string \| (row, rowIndex) => string` | | Classes for rows |
 | `rowStyle` | `CSSProperties \| (row, rowIndex) => CSSProperties` | | Inline styles for rows |
@@ -296,8 +448,9 @@ The grid is generic: `DataGrid<T>` infers `T` from `rows`, and `ColumnDef<T>` ch
 
 ```ts
 const columns: ColumnDef<Employee>[] = [
-  { field: "name", headerName: "Name" },
-  { field: "salary", headerName: "Salary", type: "number", align: "right" },
+  { field: "name", headerName: "Name", sortable: true, filterable: true },
+  { field: "salary", headerName: "Salary", type: "number", align: "right", sortable: true },
+  { field: "hired", headerName: "Hired", type: "date", sortable: true, filterable: true },
 ];
 ```
 
@@ -305,57 +458,112 @@ const columns: ColumnDef<Employee>[] = [
 | --- | --- | --- |
 | `field` | `FieldPath<T>` | **Required.** Key of the row object this column reads and writes. Use dot notation for nested objects: `"contact.phone"` |
 | `headerName` | `string` | Header text. Defaults to the field name, except in `type: "boolean"` columns, where it defaults to an empty string |
-| `type` | `"text" \| "number" \| "boolean"` | `"number"` columns edit and parse as numbers. `"boolean"` columns show a checkbox. Default `"text"` |
+| `type` | `"text" \| "number" \| "boolean" \| "date"` | `"number"` columns edit and parse as numbers, `"boolean"` columns show a checkbox, `"date"` columns have a date picker (see [6.6](#66-date-columns)). Default `"text"` |
 | `width` | `number \| string` | Header cell width |
-| `minWidth` | `number \| string` | Header cell minimum width |
+| `minWidth` / `maxWidth` | `number \| string` / `number` | Smallest and largest width (`maxWidth` limits dragging when resizing) |
 | `align` | `"left" \| "center" \| "right"` | Text alignment for the header, cells and editor |
-| `sortable` | `boolean` | Overrides the grid-level `sortable` |
+| `sortable` | `boolean` | **Opt in to sorting this column** (default `false`) |
+| `resizable` | `boolean` | Show a drag handle on the header's right edge (default `false`). See [6.17](#617-resize-pin-and-hide-columns) |
+| `pinned` | `"left" \| "right"` | Stick the column to an edge while scrolling sideways |
+| `hidden` | `boolean` | Start hidden (shown again from the Columns menu) |
+| `hideable` | `boolean` | Set `false` to keep a column out of the Columns menu (default `true`) |
 | `filterable` | `boolean` | Show a filter indicator in this column's header (default `false`). Clicking it opens the filter popup. See [6.5](#65-searching-and-filtering) |
-| `filterPlaceholder` | `string` | Placeholder of the default filter text box |
+| `filterType` | `"text" \| "exact" \| "number" \| "date" \| "select"` | Which filter controls the popup shows. Default follows `type` |
+| `filterOptions` | `(string \| FilterOption)[]` | Choices for a `"select"` filter. Without it they are built from the data |
+| `filterPlaceholder` | `string` | Placeholder of the text filter box |
 | `filterIndicator` | `ComponentType<FilterIndicatorProps<T>>` | Your own component drawn instead of the default dot |
-| `filterIndicatorClassName` | `string` | Classes for this column's indicator button |
-| `filterIndicatorStyle` | `CSSProperties` | Inline styles for this column's indicator button |
-| `filterPopupClassName` | `string` | Classes for this column's filter popup |
-| `filterPopupStyle` | `CSSProperties` | Inline styles for this column's filter popup |
+| `filterIndicatorClassName` / `filterIndicatorStyle` | `string` / `CSSProperties` | Classes and inline styles for this column's indicator button |
+| `filterPopupClassName` / `filterPopupStyle` | `string` / `CSSProperties` | Classes and inline styles for this column's filter popup |
+| `filterRenderer` | `ComponentType<FilterRendererProps<T>>` | Component that replaces the filter controls inside the popup |
 | `editable` | `boolean \| (params: CellEditableParams<T>) => boolean` | Overrides the grid-level `editable`. A function decides per cell |
-| `valueFormatter` | `(value, row) => string` | Text used for display, search, filtering. Does not change the stored value |
+| `valueFormatter` | `(value, row) => string` | Text used for display, search and text filters. Does not change the stored value |
 | `valueParser` | `(text, row) => unknown` | Turns typed text into the value to store |
 | `validate` | `(value, row) => boolean` | Return `false` to reject an edit |
 | `comparator` | `(a, b, rowA, rowB) => number` | Custom sort order |
+| `dateFormat` / `dateLocale` | `Intl.DateTimeFormatOptions` / `string` | How a `"date"` column is displayed |
+| `dateMin` / `dateMax` | `string` (`"YYYY-MM-DD"`) | Earliest and latest day the date picker accepts |
+| `exportValue` | `(value, row) => string \| number \| boolean \| null` | What goes in the CSV file for this column |
 | `cellRenderer` | `ComponentType<CellParams<T>>` | Component that renders the cell |
-| `cellEditor` | `ComponentType<CellEditorProps<T>>` | Component used instead of the text box when editing |
+| `cellEditor` | `ComponentType<CellEditorProps<T>>` | Component used instead of the built-in editor |
 | `headerRenderer` | `ComponentType<HeaderRendererProps<T>>` | Component that renders the header label |
-| `filterRenderer` | `ComponentType<FilterRendererProps<T>>` | Component that replaces the filter text box inside the popup |
-| `className` | `string` | Classes for the whole column: its header cell and every body cell (Tailwind works) |
-| `style` | `CSSProperties` | Inline styles for the whole column: its header cell and every body cell |
-| `headerClassName` | `string` | Classes for this column's header cell only |
-| `headerStyle` | `CSSProperties` | Inline styles for this column's header cell |
-| `cellClassName` | `string \| (params) => string` | Classes for this column's cells |
-| `cellStyle` | `CSSProperties \| (params) => CSSProperties` | Inline styles for this column's cells |
+| `className` / `style` | `string` / `CSSProperties` | Classes and inline styles for the whole column: header cell and every body cell (Tailwind works) |
+| `headerClassName` / `headerStyle` | `string` / `CSSProperties` | Header cell only |
+| `cellClassName` / `cellStyle` | `string \| (params) => string` / `CSSProperties \| (params) => CSSProperties` | Body cells only |
 | `checkbox` | `ColumnCheckboxOptions` | Look of the checkbox in a `type: "boolean"` column: `variant`, `indicator`, `className`, `style`, `classNames`, `styles` |
-| `headerCheckbox` | `boolean` | On a `type: "boolean"` column, draws a select-all checkbox in the header, labelled with the header name (no label when it is empty). See [Select-all header checkbox](#select-all-header-checkbox) |
+| `headerCheckbox` | `boolean` | On a `type: "boolean"` column, draws a select-all checkbox in the header. See [Select-all header checkbox](#select-all-header-checkbox) |
 
 ### 6.4 Sorting
 
+**Sorting is chosen per column.** A column is sortable only when its definition says `sortable: true`. There is no grid-level switch.
+
+```tsx
+const columns: ColumnDef<Employee>[] = [
+  { field: "id", type: "number" },                       // not sortable
+  { field: "name", sortable: true },                      // click to sort
+  { field: "salary", type: "number", sortable: true },
+];
+```
+
 - Click a header to sort ascending, click again for descending, click a third time to clear the sort.
-- Only one column is sorted at a time.
-- Numbers sort numerically, dates by time, booleans false before true. Everything else sorts as text with natural number ordering (`"item 2"` before `"item 10"`), ignoring case.
+- Numbers sort numerically, dates by day, booleans false before true. Everything else sorts as text with natural number ordering (`"item 2"` before `"item 10"`), ignoring case.
 - Empty values (`null`, `undefined`, `""`) always sort last, in both directions.
-- Add a `comparator` to sort any other way:
+- Headers are keyboard accessible (Tab to a header, Enter or Space to sort) and expose `aria-sort`. A column that is not sortable gets no sort arrow, no pointer cursor and no focus stop.
+
+**Custom order** with a `comparator`:
+
+```tsx
+const order = ["low", "medium", "high", "urgent"];
+{ field: "priority", sortable: true, comparator: (a, b) => order.indexOf(a) - order.indexOf(b) }
+```
+
+**Starting sorted** with `defaultSort`:
 
 ```tsx
-{ field: "priority", comparator: (a, b) => order.indexOf(a) - order.indexOf(b) }
+<DataGrid defaultSort={{ field: "salary", direction: "desc" }} ... />
+```
+
+**Multi-column sort.** Switch on `multiSort`. A plain click still replaces the sort with that one column. **Shift+click** adds the column as the next tie-breaker (or cycles its direction if it is already in the sort). Small numbers in the headers show the priority.
+
+```tsx
+<DataGrid
+  multiSort
+  defaultSort={[
+    { field: "department", direction: "asc" },
+    { field: "salary", direction: "desc" },   // inside each department, highest salary first
+  ]}
+  columns={columns}
+  rows={rows}
+/>
 ```
 
-- Set an initial sort with `defaultSort={{ field: "salary", direction: "desc" }}` and react to changes with `onSortChange`.
-- Headers are keyboard accessible (Tab to a header, Enter or Space to sort) and expose `aria-sort`.
-- Turn sorting off for the whole grid with `sortable={false}` or per column with `sortable: false`.
+**Reacting to the sort** (always an array, empty when unsorted):
+
+```tsx
+<DataGrid
+  onSortChange={(sort) => console.log(sort)}
+  // [{ field: "department", direction: "asc" }, { field: "salary", direction: "desc" }]
+  ...
+/>
+```
+
+**Controlling the sort yourself** (also see [6.14](#614-controlled-state)):
+
+```tsx
+const [sort, setSort] = useState<SortModel[]>([{ field: "name", direction: "asc" }]);
+
+<button onClick={() => setSort([])}>Reset sort</button>
+<DataGrid sort={sort} onSortChange={setSort} ... />
+```
 
 ### 6.5 Searching and filtering
 
-**Global search.** The box above the grid matches rows where any column's displayed text contains the typed text (case-insensitive). "Displayed text" means the result of `valueFormatter` if there is one.
+**Global search.** Off by default. Switch it on with `searchable` and a box appears above the grid. It matches rows where any column's displayed text contains the typed text (case-insensitive). "Displayed text" means the result of `valueFormatter` if there is one.
+
+```tsx
+<DataGrid searchable searchPlaceholder="Search people…" ... />
+```
 
-**Column filters.** Filters are set per column, in the column definition. Only columns with `filterable: true` get one:
+**Column filters.** Filters are set per column. Only columns with `filterable: true` get one:
 
 ```tsx
 const columns: ColumnDef<Person>[] = [
@@ -366,13 +574,84 @@ const columns: ColumnDef<Person>[] = [
 ```
 
 - A filterable column shows a small **indicator** in its header, next to the label. By default it is a dot. It is dim while no filter is set, and lit (with a glow) while one is active.
-- **Clicking the indicator** opens a popup right below it with a text box. The popup is not there until you click. It closes on Escape, on a click outside, or on Enter in the text box. Clicking the indicator does not sort the column.
+- **Clicking the indicator** opens a popup right below it. The popup is not there until you click. It closes on Escape, on a click outside, or on Enter in a text box. Clicking the indicator does not sort the column.
 - The popup shows a **Clear** button while a filter is set.
-- Filters work as a case-insensitive "contains" on the displayed text, and combine with each other and with the global search.
+- All filters and the global search combine (a row must pass every one).
 - The popup is drawn in `document.body` and positioned next to the indicator, so a scrolling grid never clips it. It follows scrolling and resizing, and stays inside the window.
-- There is no grid-level filter prop: a column without `filterable: true` has no filter, and a filter value is ignored if its column stops being filterable.
+- There is no grid-level filter prop to turn filters on: a column without `filterable: true` has no filter, and a filter value is ignored if its column stops being filterable.
 
-**Styling each indicator separately.** Every column has its own options:
+#### Filter types
+
+Each column's filter has a kind. By default it follows the column `type`; set `filterType` to choose another.
+
+| `filterType` | Default for | Popup shows | Rows pass when |
+| --- | --- | --- | --- |
+| `"text"` | `type: "text"` | One text box | The displayed text **contains** the typed text (case-insensitive) |
+| `"exact"` | | One text box | The displayed text **equals** the typed text (case-insensitive) |
+| `"number"` | `type: "number"` | Min and Max boxes | The number is between Min and Max (either may be left empty). Rows without a number never match |
+| `"date"` | `type: "date"` | From and To date pickers | The day is between From and To (either may be left empty) |
+| `"select"` | `type: "boolean"` | A checkbox per value | The raw value is one of the ticked values |
+
+```tsx
+const columns: ColumnDef<Task>[] = [
+  // "contains": typing "log" finds "Fix login" and "Catalogue"
+  { field: "title", filterable: true },
+
+  // "exact": typing "active" finds "active" but NOT "inactive"
+  { field: "status", filterable: true, filterType: "exact" },
+
+  // number range: type: "number" gives a Min / Max popup by default
+  { field: "budget", type: "number", filterable: true },
+
+  // date range: type: "date" gives From / To date pickers by default
+  { field: "due", type: "date", filterable: true },
+
+  // choose from a list: values are collected from the data...
+  { field: "owner", filterable: true, filterType: "select" },
+
+  // ...or you decide the list and the labels
+  {
+    field: "priority",
+    filterable: true,
+    filterType: "select",
+    filterOptions: [
+      { value: "p1", label: "Urgent" },
+      { value: "p2", label: "Normal" },
+      "p3",                              // a plain string is its own label
+    ],
+  },
+];
+```
+
+Notes on `select`: when `filterOptions` is left out, the choices are the distinct values in the data, sorted. A boolean column gets "Yes" and "No". Ticking several values combines them with OR.
+
+#### Reading and setting filters
+
+The shape of a filter value depends on its kind:
+
+```ts
+// text / exact:  "sales"
+// number:        { min: 1000, max: 5000 }        (either key may be missing)
+// date:          { from: "2026-01-01", to: "2026-03-31" }
+// select:        ["active", "pending"]
+```
+
+Listen with `onFiltersChange`, or control the filters completely:
+
+```tsx
+const [filters, setFilters] = useState<Record<string, FilterValue>>({
+  status: ["open", "blocked"],                  // select
+  budget: { min: 1000 },                        // number
+  due: { from: "2026-06-01" },                  // date
+});
+
+<button onClick={() => setFilters({})}>Clear all filters</button>
+<DataGrid filters={filters} onFiltersChange={setFilters} ... />
+```
+
+#### Styling each indicator
+
+Every column has its own options:
 
 ```tsx
 {
@@ -386,7 +665,9 @@ const columns: ColumnDef<Person>[] = [
 
 The dot takes its colour from the button's text colour, so `color` (or `text-*`) restyles it. The colour while a filter is active comes from `--rk-filter-active`. To style all indicators or popups at once, use `classNames.filterIndicator`, `classNames.filterPopup`, `classNames.filterInput` (or the matching `styles`).
 
-**A custom indicator component.** Replace the dot with any component. It receives `{ column, active, open }`:
+#### A custom indicator component
+
+Replace the dot with any component. It receives `{ column, active, open }`:
 
 ```tsx
 function FunnelIndicator({ active }: FilterIndicatorProps<Employee>) {
@@ -402,49 +683,123 @@ function FunnelIndicator({ active }: FilterIndicatorProps<Employee>) {
 
 The component is drawn inside the indicator `<button>`, so do not put another button in it.
 
-**A custom filter control.** `filterRenderer` replaces the text box inside the popup (see [filterRenderer](#filterrenderer-custom-filter-control)).
+#### A custom filter control
+
+`filterRenderer` replaces **all** the built-in controls inside the popup, whatever the filter type (see [filterRenderer](#filterrenderer-custom-filter-control)). A custom control produces a text filter, so it works with the "contains" matching.
 
-Notes:
+#### Notes
 
-- Searching and filtering use the displayed text, so a salary shown as `$52,000` is found by `52,000` and not by `52000` unless your formatter says so.
-- Filtering is a substring match. Filtering a status column for `active` also matches `inactive`. For exact choices, use a `filterRenderer` and a distinct display text, or format the values so they don't overlap.
+- Searching and text filters use the displayed text, so a salary shown as `$52,000` is found by `52,000` and not by `52000` unless your formatter says so. Number, date and select filters look at the raw value instead, so formatting never gets in their way.
 - Changing the search, a filter, the sort or the page size sends the grid back to page 1.
-- Turn off the search box with `searchable={false}`. Leave out `filterable` (or set it to `false`) to give a column no filter.
+- In [server-side mode](#615-server-side-mode) the filters are not applied by the grid: they are handed to your server in the query.
 
-### 6.6 Pagination
+### 6.6 Date columns
+
+`type: "date"` is a built-in column type with formatting, a date picker editor, chronological sorting and a From / To filter.
 
 ```tsx
-<DataGrid pageSize={20} pageSizeOptions={[10, 20, 50, 100]} paginationPosition="both" />
+interface Task { id: number; title: string; due: string; created: Date }
+
+const columns: ColumnDef<Task>[] = [
+  { field: "title", editable: true },
+  {
+    field: "due",
+    type: "date",
+    sortable: true,
+    filterable: true,
+    editable: true,
+    dateMin: "2026-01-01",           // the picker will not accept earlier days
+    dateMax: "2027-12-31",
+  },
+];
+
+<DataGrid columns={columns} rows={tasks} editable onRowsChange={setTasks} />
 ```
 
-The pagination bar shows the row range ("11–20 of 200"), a rows-per-page menu, first/previous/next/last buttons and "Page x of y".
+**What a row may hold.** The cell understands `"2026-11-05"`, a full ISO string (`"2026-11-05T10:30:00Z"`, whose date part is used as written), a `Date` object, a timestamp number, or any string `Date.parse` understands. Empty values show blank and sort last. Text that is not a date is shown as it is.
+
+**Editing.** Double-click a date cell (or press Enter / F2) to open the browser's date picker. Typing characters does not start an editor on a date cell, because the picker is its own control. After picking or typing a valid date, Enter or a click elsewhere saves it. An empty picker saves `null`. Escape cancels. A half-typed date is ignored when you click away.
+
+**The saved value keeps the shape the row already had.**
+
+| Row held | Saved value |
+| --- | --- |
+| `"2026-03-14"` (text) | `"2026-03-14"` |
+| a `Date` object | a `Date` at local midnight |
+| a timestamp number | a timestamp at local midnight |
+| empty | the same shape as the other rows in the column (the ISO text when there are none) |
+
+Dates are handled in the **user's local time zone**, so typing 5 November never turns into 4 November because of UTC.
+
+**Display.** The default is the browser's medium date format (`Nov 5, 2026`). Change it with `dateLocale` and `dateFormat` (any `Intl.DateTimeFormat` options):
+
+```tsx
+{ field: "created", type: "date", dateLocale: "en-GB", dateFormat: { dateStyle: "long" } }  // 5 November 2026
+{ field: "created", type: "date", dateLocale: "de-DE", dateFormat: { day: "2-digit", month: "2-digit", year: "numeric" } } // 05.11.2026
+```
+
+A `valueFormatter` still wins over these two if you set one.
+
+**Sorting and filtering.** Dates sort by day (earliest first, empties last). The filter popup has From and To pickers; either may be empty for an open-ended range:
+
+```tsx
+<DataGrid filters={{ due: { from: "2026-03-01", to: "2026-06-30" } }} onFiltersChange={setFilters} ... />
+```
+
+**CSV export** writes dates as `"YYYY-MM-DD"` unless you give `exportValue`.
+
+### 6.7 Pagination
+
+Pagination is off by default. Switch it on to split the rows into pages and show the bar with the row range ("11–20 of 200"), a rows-per-page menu, first / previous / next / last buttons and "Page x of y". **The bar (and its page information) only appears when `pagination` is passed.**
+
+```tsx
+<DataGrid pagination pageSize={20} pageSizeOptions={[10, 20, 50, 100]} paginationPosition="both" ... />
+```
 
 | `paginationPosition` | Result |
 | --- | --- |
 | `"bottom"` | Bar under the table (default) |
-| `"top"` | Bar above the table, below the search box |
+| `"top"` | Bar above the table, below the toolbar |
 | `"both"` | Both bars, kept in sync |
 
-With `pagination={false}` every row is rendered and only the row count shows, at the bottom. Combine it with `maxHeight` to get a scrolling grid with a sticky header:
+Without `pagination` every row is rendered and there is no footer at all. Combine it with `maxHeight` for a scrolling grid with a sticky header:
 
 ```tsx
-<DataGrid pagination={false} maxHeight={400} />
+<DataGrid maxHeight={400} ... />
 ```
 
-`pageSize` is only read when the grid first mounts. The user's choice in the menu is then kept inside the grid.
+`pageSize` is only read when the grid first mounts. The user's choice in the menu is then kept inside the grid. To own the page, see [6.14](#614-controlled-state).
+
+**Reacting to paging:**
+
+```tsx
+<DataGrid
+  pagination
+  onPageChange={(page) => console.log("page", page)}          // zero-based
+  onPageSizeChange={(size) => localStorage.setItem("size", String(size))}
+  pageSize={Number(localStorage.getItem("size")) || 10}
+  ...
+/>
+```
 
-### 6.7 Row click, toolbar and empty state
+### 6.8 Row click, toolbar and empty state
 
 ```tsx
 <DataGrid
   onRowClick={(row, rowIndex) => navigate(`/people/${row.id}`)}
-  toolbar={<button onClick={exportCsv}>Export</button>}
+  toolbar={<button onClick={openNewPersonDialog}>Add person</button>}
   emptyMessage="Nothing matches your search"
   striped
 />
 ```
 
-### 6.8 Editing
+The toolbar row is drawn when at least one of `searchable`, `columnMenu`, `exportable` or `toolbar` is used. Your `toolbar` content sits on the right, next to the built-in buttons. To style a toolbar button the same way as the built-in ones, give it the class `rk-grid__tool-btn`:
+
+```tsx
+toolbar={<button className="rk-grid__tool-btn" onClick={refetch}>Reload</button>}
+```
+
+### 6.9 Editing
 
 Turn editing on with `editable` on the grid, then lock or unlock columns:
 
@@ -531,7 +886,7 @@ Important: the grid copies `rows` into its own state and re-syncs whenever the `
 />
 ```
 
-### 6.9 Custom components per column
+### 6.10 Custom components per column
 
 Four hooks let you replace parts of a column with your own React components. They are rendered as real components, so they can use hooks and state.
 
@@ -638,7 +993,7 @@ function DepartmentFilter({ value, onChange }: FilterRendererProps<Employee>) {
 
 #### Checkbox columns (`type: "boolean"`)
 
-Set `type: "boolean"` on a column and each cell shows a [Checkbox](#checkbox). One click saves the new `true` / `false` value.
+Set `type: "boolean"` on a column and each cell shows a [Checkbox](#5-checkbox). One click saves the new `true` / `false` value.
 
 ```tsx
 const columns: ColumnDef<Task>[] = [
@@ -727,7 +1082,7 @@ Add `headerCheckbox: true` to a boolean column. The header label becomes a check
 - **Sorting:** clicking the checkbox or its label does not sort. Click the sort arrow beside it (or the empty part of the header cell) to sort.
 - **Custom header:** if the column also has a `headerRenderer`, that is used and `headerCheckbox` is ignored. `headerCheckbox` does nothing on columns that are not `type: "boolean"`.
 
-### 6.10 Styling
+### 6.11 Styling
 
 #### Whole grid
 
@@ -762,6 +1117,8 @@ Add `headerCheckbox: true` to a boolean column. The header label becomes a check
 | `pageInfo` | The "Page 1 of 20" text |
 | `pageSize` | The rows-per-page `<select>` |
 | `pagination` | Wrapper around the page-size menu and buttons |
+| `toolButton` | Toolbar buttons (Columns, Export CSV, Retry) |
+| `skeleton` | The shimmering bars of the loading skeleton |
 | `pageButton` | Each first/previous/next/last button |
 | `checkbox` | Root of each checkbox in a `type: "boolean"` column |
 | `checkboxControl` | The checkbox's button or input |
@@ -859,12 +1216,22 @@ If you prefer writing CSS, these class names are stable.
 | `.rk-grid__td`, `.rk-grid__td--editable`, `.rk-grid__td--editing` | Body cells |
 | `.rk-grid__editor`, `.rk-grid__editor--invalid`, `.rk-grid__custom-editor` | Editors |
 | `.rk-grid__empty` | Empty state |
-| `.rk-grid__checkbox-cell` | Wrapper around a checkbox in a boolean column (the checkbox's own classes start with `.rk-checkbox`, see [Checkbox](#checkbox)) |
+| `.rk-grid__checkbox-cell` | Wrapper around a checkbox in a boolean column (the checkbox's own classes start with `.rk-checkbox`, see [Checkbox](#5-checkbox)) |
 | `.rk-grid__footer`, `.rk-grid__footer--top` | Pagination bar (`data-position="top"` or `"bottom"`) |
 | `.rk-grid__count`, `.rk-grid__pagination`, `.rk-grid__page-size-label`, `.rk-grid__page-size`, `.rk-grid__page-btn`, `.rk-grid__page-info` | Pagination parts |
+| `.rk-grid__toolbar-left`, `.rk-grid__toolbar-actions` | The two halves of the toolbar (search and selected count / buttons) |
+| `.rk-grid__tool-btn`, `.rk-grid__selected-count` | Toolbar buttons and the "N selected" label |
+| `.rk-grid__select-cell`, `.rk-grid__row--selected` | Row-selection checkbox cell and a selected row |
+| `.rk-grid__pinned`, `.rk-grid__pinned--left`, `.rk-grid__pinned--right`, `.rk-grid__pinned--edge` | Pinned cells (the edge class marks the last left / first right one) |
+| `.rk-grid__resizer` | The column resize handle |
+| `.rk-grid__sort-order` | The priority number next to a sort arrow in multi-column sort |
+| `.rk-grid--virtual`, `.rk-grid__spacer` | Virtualized grid and its spacer rows |
+| `.rk-grid__skeleton`, `.rk-grid__skeleton-row`, `.rk-grid__skeleton-cell` | Loading placeholder bar, row and (custom) cell |
+| `.rk-grid__error` | The error message cell (with the Retry button) |
+| `.rk-grid__filter-fields`, `.rk-grid__filter-field`, `.rk-grid__filter-options`, `.rk-grid__filter-empty` | Controls inside the filter popup (number, date, select) |
 
 
-### 6.11 Nested fields
+### 6.12 Nested fields
 
 A column's `field` can point into nested objects with dot notation:
 
@@ -892,54 +1259,560 @@ const columns: ColumnDef<Person>[] = [
 - `__proto__`, `prototype` and `constructor` are never read or written through a path.
 - `getRowId`, `onRowClick` and other callbacks work as before.
 
-### 6.12 Keyboard reference
+### 6.13 Row selection
+
+Off by default. `rowSelection` adds a checkbox column on the left.
+
+```tsx
+<DataGrid columns={columns} rows={rows} getRowId={(r) => r.id} rowSelection />
+```
+
+| Value | Behaviour |
+| --- | --- |
+| `true` or `"multiple"` | Many rows. The header has a select-all checkbox. Shift+click selects a range |
+| `"single"` | One row at a time (selecting another replaces it). No select-all checkbox |
+
+- Selected rows get the class `rk-grid__row--selected`, the colour `--rk-selected-bg` and `aria-selected="true"`.
+- Selection is kept **by row id**, so it survives paging, sorting, searching and filtering. Pass `getRowId` so ids are stable.
+- The **select-all checkbox** in the header acts on every selectable row that matches the current search and filters, **across all pages**. It shows a dash while only some of them are selected.
+- **Shift+click** on a row's checkbox selects (or clears) everything between it and the last row you clicked, as shown on screen. Disabled rows in between are skipped.
+- A "N selected" count appears in the toolbar (when a toolbar is shown) and in the pagination bar.
+
+**Reading the selection** (`onSelectionChange` receives the ids and the row objects):
+
+```tsx
+function Page() {
+  const [selection, setSelection] = useState<RowSelection<Person>>({ ids: [], rows: [] });
+
+  return (
+    <>
+      <button disabled={!selection.ids.length} onClick={() => deletePeople(selection.ids)}>
+        Delete {selection.ids.length} people
+      </button>
+      <DataGrid
+        columns={columns}
+        rows={rows}
+        getRowId={(r) => r.id}
+        rowSelection
+        onSelectionChange={setSelection}
+      />
+    </>
+  );
+}
+```
+
+**Controlled selection.** Pass `selectedRowIds` and keep it up to date from `onSelectionChange`:
+
+```tsx
+const [ids, setIds] = useState<(string | number)[]>([2, 4]);
+
+<button onClick={() => setIds([])}>Clear</button>
+<DataGrid rowSelection selectedRowIds={ids} onSelectionChange={(s) => setIds(s.ids)} ... />
+```
+
+Or start with some rows selected and let the grid manage it: `defaultSelectedRowIds={[2, 4]}`.
+
+**Rows that cannot be selected.** Return `false` from `isRowSelectable`. The row's checkbox is disabled, select-all skips it and Shift ranges pass over it:
+
+```tsx
+<DataGrid rowSelection isRowSelectable={(row) => row.status !== "archived"} ... />
+```
+
+**Single selection**, for a master / detail layout:
+
+```tsx
+const [current, setCurrent] = useState<Person | null>(null);
+
+<DataGrid
+  rowSelection="single"
+  getRowId={(r) => r.id}
+  onSelectionChange={(s) => setCurrent(s.rows[0] ?? null)}
+  ...
+/>
+{current && <PersonDetails person={current} />}
+```
+
+**From outside the grid**, with `apiRef` (see [6.19](#619-csv-export-and-the-api)):
+
+```tsx
+const api = useRef<DataGridApi<Person> | null>(null);
+
+<button onClick={() => api.current?.selectAll()}>Select all</button>
+<button onClick={() => api.current?.clearSelection()}>Clear</button>
+<button onClick={() => console.log(api.current?.getSelectedRows())}>Log selection</button>
+<DataGrid rowSelection apiRef={api} ... />
+```
+
+**Combined with other features.** Row selection works together with pinning (the checkbox column is pinned automatically when any column is pinned left), virtualization, keyboard navigation, and CSV export (`scope: "selected"`).
+
+**In server-side mode** the grid only holds the current page, so it remembers every row it has seen. `onSelectionChange` and `getSelectedRows()` return those remembered rows, including ones selected on pages you have left. Select-all selects the rows of the page that is loaded.
+
+### 6.14 Controlled state
+
+Search, filters, sort, page and selection can each be **uncontrolled** (the grid keeps the state; the default) or **controlled** (you pass the value and the change callback).
+
+| State | Value prop | Change callback | Initial value (uncontrolled) |
+| --- | --- | --- | --- |
+| Search text | `search` | `onSearchChange(text)` | |
+| Column filters | `filters` | `onFiltersChange(filters)` | |
+| Sort | `sort` | `onSortChange(sort)` | `defaultSort` |
+| Page (zero-based) | `page` | `onPageChange(page)` | page 0 |
+| Page size | | `onPageSizeChange(size)` | `pageSize` |
+| Selection | `selectedRowIds` | `onSelectionChange({ ids, rows })` | `defaultSelectedRowIds` |
+
+**Rules.**
+
+- Pass the value **and** its callback. A value without a callback makes that piece of state read-only.
+- You may control some pieces and leave the rest to the grid.
+- The page goes back to 0 automatically whenever the search, a filter, the sort or the page size changes. In a controlled grid you receive that through `onPageChange(0)`.
+
+**Example: keep the grid in sync with the URL** so a page can be bookmarked and the Back button works:
+
+```tsx
+import { useSearchParams } from "react-router-dom";
+
+function PeopleGrid() {
+  const [params, setParams] = useSearchParams();
+  const page = Number(params.get("page") ?? 0);
+  const search = params.get("q") ?? "";
+
+  const update = (changes: Record<string, string | null>) =>
+    setParams((p) => {
+      for (const [k, v] of Object.entries(changes)) v === null ? p.delete(k) : p.set(k, v);
+      return p;
+    });
+
+  return (
+    <DataGrid
+      columns={columns}
+      rows={rows}
+      searchable
+      pagination
+      page={page}
+      onPageChange={(p) => update({ page: String(p) })}
+      search={search}
+      onSearchChange={(q) => update({ q: q || null })}
+    />
+  );
+}
+```
+
+**Example: buttons outside the grid**
+
+```tsx
+const [page, setPage] = useState(0);
+const [search, setSearch] = useState("");
+
+<button onClick={() => setPage(2)}>Go to page 3</button>
+<input value={search} onChange={(e) => setSearch(e.target.value)} placeholder="Search outside the grid" />
+<DataGrid searchable pagination pageSize={5} page={page} onPageChange={setPage} search={search} onSearchChange={setSearch} ... />
+```
+
+**Example: saved views.** Remember a user's filters and sort between visits:
+
+```tsx
+const [filters, setFilters] = useState<Record<string, FilterValue>>(() => JSON.parse(localStorage.getItem("filters") ?? "{}"));
+const [sort, setSort] = useState<SortModel[]>(() => JSON.parse(localStorage.getItem("sort") ?? "[]"));
+
+useEffect(() => localStorage.setItem("filters", JSON.stringify(filters)), [filters]);
+useEffect(() => localStorage.setItem("sort", JSON.stringify(sort)), [sort]);
+
+<DataGrid filters={filters} onFiltersChange={setFilters} sort={sort} onSortChange={setSort} ... />
+```
+
+### 6.15 Server-side mode
+
+When your data lives on a server, switch on `serverSide`. The grid then **does not sort, filter, search or page the rows itself**. It shows the `rows` you give it (the current page) and tells you what to fetch.
+
+```tsx
+<DataGrid
+  serverSide
+  columns={columns}
+  rows={rows}               // only the current page
+  rowCount={total}          // total rows on the server, for "1–10 of 237" and the page count
+  pagination
+  searchable
+  onQueryChange={load}
+/>
+```
+
+`onQueryChange(query)` is called **on mount and whenever the query changes**: the sort, the search text (after `queryDebounce` ms), a filter, the page or the page size. The query is:
+
+```ts
+interface GridQuery {
+  sort: SortModel[];                      // [{ field: "salary", direction: "desc" }]
+  filters: Record<string, FilterValue>;   // only active ones, by field
+  search: string;                         // trimmed
+  page: number;                           // zero-based
+  pageSize: number;
+}
+```
+
+Filter values have the shapes from [6.5](#65-searching-and-filtering): a string for text / exact, `{ min, max }` for number, `{ from, to }` for date, an array for select. Only columns marked `sortable` appear in `sort`.
+
+**Loading is caught from a function.** If `onQueryChange` returns a promise, the grid shows the [loading skeleton](#616-loading-skeleton) until the promise settles. If it rejects, the grid shows `errorMessage` with a **Retry** button that runs the same query again. You do not manage any `loading` state.
+
+```tsx
+function PeopleGrid() {
+  const [rows, setRows] = useState<Person[]>([]);
+  const [total, setTotal] = useState(0);
+
+  const load = useCallback(async (q: GridQuery) => {
+    const res = await fetch("/api/people?" + new URLSearchParams({
+      page: String(q.page),
+      pageSize: String(q.pageSize),
+      search: q.search,
+      sort: JSON.stringify(q.sort),
+      filters: JSON.stringify(q.filters),
+    }));
+    if (!res.ok) throw new Error("Request failed");   // -> error row with Retry
+    const body = await res.json();
+    setRows(body.rows);
+    setTotal(body.total);
+  }, []);
+
+  return (
+    <DataGrid
+      serverSide
+      columns={columns}
+      rows={rows}
+      rowCount={total}
+      getRowId={(r) => r.id}
+      pagination
+      searchable
+      onQueryChange={load}
+      errorMessage="Could not reach the server."
+    />
+  );
+}
+```
+
+**Ignoring stale answers.** The grid ignores the *loading state* of an older query when a newer one has started, but it cannot know which response **you** store. Cancel old requests with `AbortController`, or compare a counter:
+
+```tsx
+const controller = useRef<AbortController>();
+
+const load = useCallback(async (q: GridQuery) => {
+  controller.current?.abort();                         // cancel the previous request
+  controller.current = new AbortController();
+  const res = await fetch(url(q), { signal: controller.current.signal });
+  const body = await res.json();
+  setRows(body.rows);
+  setTotal(body.total);
+}, []);
+```
+
+An aborted `fetch` rejects with an `AbortError`. If you do not want that to show the error row, catch it: `catch (e) { if ((e as Error).name !== "AbortError") throw e; }`.
+
+**Using a data library.** Anything that returns a promise works:
+
+```tsx
+// the grid calls your function; you call the library
+const load = (q: GridQuery) => queryClient.fetchQuery({ queryKey: ["people", q], queryFn: () => api.people(q) })
+  .then((res) => { setRows(res.rows); setTotal(res.total); });
+```
+
+**Forcing the loading state.** If your loading flag lives somewhere else (a hook, a store), pass `loading` and it replaces the promise-based state:
+
+```tsx
+const { data, isFetching } = useQuery(...);
+<DataGrid serverSide rows={data?.rows ?? []} rowCount={data?.total} loading={isFetching} onQueryChange={setQuery} />
+```
+
+**Refreshing** after your data changed (for example after deleting a row) runs the last query again:
+
+```tsx
+api.current?.refresh();
+```
+
+**Search debounce.** Typing in the search box waits `queryDebounce` milliseconds (250 by default) after the last keystroke, so fast typing makes one request, not one per letter. Set `queryDebounce={0}` for instant queries.
+
+**Server mode and the other features.**
+
+- Selection, [CSV export of selected rows](#619-csv-export-and-the-api) and keyboard navigation work on the loaded page.
+- With `scope: "filtered"` the CSV contains the rows currently loaded (the current page), because the grid does not have the rest.
+- `defaultSort` is sent in the first query. `multiSort` lets users send several sort columns.
+- `onQueryChange` is the only place the grid asks for data. Without `serverSide`, the grid never calls it.
+
+### 6.16 Loading skeleton
+
+While loading, the body shows **placeholder rows** with shimmering bars instead of data. The header, toolbar and footer stay in place, and the grid root gets `aria-busy="true"`. When the promise from `onQueryChange` settles (or `loading` turns `false`), the real rows appear.
+
+```tsx
+<DataGrid serverSide onQueryChange={load} loadingRows={8} ... />
+```
+
+- `loadingRows` is how many placeholder rows to draw. Default: the page size (at most 20), or 5 without pagination.
+- With `rowSelection` the checkbox column shows a small bar too.
+- Bar widths vary slightly from row to row so the placeholder does not look like identical stripes.
+- Colours come from `--rk-skeleton-a` and `--rk-skeleton-b`. Each theme sets them. The shimmer stops when the user has "reduce motion" turned on.
+- Style the bars with `classNames.skeleton` / `styles.skeleton` (they are `<span class="rk-grid__skeleton">`).
+
+**A custom skeleton for each row.** Pass a component as `skeletonRow`. It is drawn once per placeholder row, inside a single cell that spans the whole row, and receives `{ rowIndex, columns }`:
+
+```tsx
+function PersonSkeleton({ rowIndex }: SkeletonRowProps<Person>) {
+  return (
+    <div style={{ display: "flex", gap: 12, alignItems: "center", padding: "4px 0" }}>
+      <span className="avatar-skeleton" />
+      <span style={{ display: "grid", gap: 6, flex: 1 }}>
+        <span className="line-skeleton" style={{ width: `${40 + ((rowIndex * 17) % 30)}%` }} />
+        <span className="line-skeleton" style={{ width: "25%" }} />
+      </span>
+    </div>
+  );
+}
+
+<DataGrid serverSide onQueryChange={load} skeletonRow={PersonSkeleton} loadingRows={6} ... />
+```
+
+You can reuse the built-in shimmer in your own placeholder by giving your elements the class `rk-grid__skeleton`:
+
+```tsx
+function RowSkeleton({ columns }: SkeletonRowProps<Person>) {
+  return (
+    <div style={{ display: "grid", gridTemplateColumns: `repeat(${columns.length}, 1fr)`, gap: 16 }}>
+      {columns.map((c) => <span key={c.field} className="rk-grid__skeleton" style={{ width: "70%" }} />)}
+    </div>
+  );
+}
+```
+
+Define the skeleton component at module level (not inline in render), like every other custom component.
+
+**Showing it without a server.** `loading` works in a normal grid too, for example while a parent fetches `rows`:
+
+```tsx
+<DataGrid columns={columns} rows={rows} loading={isLoading} />
+```
+
+**The error state.** If the promise from `onQueryChange` rejects, the body shows `errorMessage` (default "Could not load the data.") and a Retry button. Style it with `.rk-grid__error`:
+
+```tsx
+<DataGrid serverSide onQueryChange={load} errorMessage={<strong>The server is not answering.</strong>} ... />
+```
+
+### 6.17 Resize, pin and hide columns
+
+All three are opt-in. **There is no column reordering.**
+
+**Resizing.** Add `resizable: true` to a column. A drag handle appears on its right edge. Drag it, or use a touch or pen: it uses pointer events.
+
+```tsx
+const columns: ColumnDef<Employee>[] = [
+  { field: "name", resizable: true, minWidth: 100 },
+  { field: "email", resizable: true, minWidth: 140, maxWidth: 480 },
+  { field: "id", width: 70 },                       // no handle: fixed
+];
+```
+
+- On the first drag the grid fixes every column at the width it has at that moment (so nothing jumps) and switches the table to `table-layout: fixed`.
+- `minWidth` (at least 40px) and `maxWidth` limit the drag.
+- Widths live inside the grid and are not saved. To remember them, store the `width` you want per column yourself.
+
+**Pinning.** Add `pinned: "left"` or `"right"` to keep a column visible while the rest scrolls sideways. Pinned columns are moved to the edges (left-pinned first, right-pinned last), keep their order among themselves, and have an opaque background.
+
+```tsx
+const columns: ColumnDef<Employee>[] = [
+  { field: "id", width: 70, pinned: "left" },
+  { field: "name", width: 160, pinned: "left" },    // sits next to ID
+  { field: "email", width: 280 },
+  { field: "department", width: 200 },
+  { field: "salary", width: 160 },
+  { field: "status", width: 120, pinned: "right" }, // always at the right edge
+];
+
+<DataGrid columns={columns} rows={rows} />          // scroll sideways: ID, Name and Status stay put
+```
+
+The row-selection checkbox column is pinned too when any column is pinned left. A thin shadow line (`.rk-grid__pinned--edge`) marks where pinned columns end. Give pinned columns an explicit `width` for the cleanest look. Pinning needs the grid to be narrower than its columns, which happens when the columns' widths add up to more than the container.
+
+Colours: `--rk-pinned-bg` and `--rk-pinned-header-bg`. Stripes, hover and selection are layered on top.
+
+**Showing and hiding.** Switch on `columnMenu` for a "Columns" button with a checkbox per column:
+
+```tsx
+<DataGrid
+  columnMenu
+  onColumnVisibilityChange={(hiddenFields) => localStorage.setItem("hidden", JSON.stringify(hiddenFields))}
+  columns={[
+    { field: "id", hideable: false },               // always visible, not listed
+    { field: "name" },
+    { field: "email" },
+    { field: "notes", hidden: true },               // starts hidden
+  ]}
+  rows={rows}
+/>
+```
+
+- `hidden: true` starts a column hidden. The menu shows it unchecked.
+- `hideable: false` keeps a column out of the menu, so it cannot be hidden.
+- The last visible column cannot be hidden.
+- Hidden columns are skipped by search, keyboard navigation and CSV export (unless `includeHidden`).
+
+### 6.18 Keyboard
+
+Switch on `keyboardNavigation` to move between cells with the keyboard. The grid has **one tab stop**: Tab enters the body at the last cell you used (or the first one), and the arrow keys move from there. Tab again leaves the grid.
+
+| Key (on a cell) | Action |
+| --- | --- |
+| Arrow keys | Move one cell |
+| Home / End | First / last column of the row |
+| Ctrl+Home / Ctrl+End | First cell of the first row / last cell of the last row |
+| Page Up / Page Down | Move 10 rows |
+| Enter / F2 | Start editing (editable cells) |
+| Any character | Start editing and replace the value (text and number cells) |
+
+Other keys, always available:
 
 | Where | Key | Action |
 | --- | --- | --- |
-| Header | Enter / Space | Sort by this column |
-| Selected cell | Enter / F2 | Start editing |
-| Selected cell | Any character | Start editing, replacing the value |
-| Editor | Enter | Save, edit cell below |
-| Editor | Shift+Enter | Save, edit cell above |
-| Editor | Tab / Shift+Tab | Save, edit next / previous cell |
+| Header | Enter / Space | Sort by this column (sortable columns) |
+| Editor | Enter | Save, edit the cell below |
+| Editor | Shift+Enter | Save, edit the cell above |
+| Editor | Tab / Shift+Tab | Save, edit the next / previous cell |
 | Editor | Esc | Cancel |
+| Filter popup | Esc | Close |
+| Text filter box | Enter | Close the popup |
+
+With `virtualize`, moving past the visible window scrolls the target row into view before focusing it, so you can arrow through 20,000 rows. Combined with `maxHeight`, the focused cell is scrolled into view.
+
+```tsx
+<DataGrid keyboardNavigation editable maxHeight={420} columns={columns} rows={rows} />
+```
 
-Arrow-key navigation between cells is not implemented. Use Tab, or the mouse, to select a cell.
+Without `keyboardNavigation`, cells are reachable with Tab (editable cells) or the mouse, as before.
 
-### 6.13 Accessibility
+### 6.19 CSV export and the API
 
-- The table has `role="grid"`. Sortable headers are focusable, expose `aria-sort`, and work with Enter and Space.
-- Editable cells are focusable (`tabindex="0"`).
-- The search box, filter indicators (`aria-haspopup="dialog"`, `aria-expanded`), filter popups (`role="dialog"`), editors, page buttons and page-size menu have `aria-label`s. Checkboxes in columns with an empty header are named after the field.
+**The export button.** Switch on `exportable` for an "Export CSV" button in the toolbar. It downloads what the user sees: the visible columns, in order, for every row matching the search and filters (across all pages).
+
+```tsx
+<DataGrid exportable ... />                                                   // downloads export.csv
+<DataGrid exportable={{ filename: "employees" }} ... />                        // employees.csv
+<DataGrid exportable={{ filename: "page-1", scope: "page" }} ... />            // only the current page
+<DataGrid exportable={{ scope: "selected" }} rowSelection ... />               // only the selected rows
+```
+
+| `ExportOptions` | Default | Meaning |
+| --- | --- | --- |
+| `filename` | `"export"` | File name without `.csv` |
+| `scope` | `"filtered"` | `"filtered"` all rows matching search and filters, `"page"` the current page, `"selected"` the selected rows |
+| `includeHidden` | `false` | Also write hidden columns |
+| `sanitize` | `true` | Put an apostrophe in front of text starting with `=`, `+`, `-` or `@`, so Excel does not run it as a formula |
+
+**What goes in the file.** The header row uses the column header names. Cell values are the displayed text (the result of `valueFormatter`, `Yes` / `No` for booleans), except that dates are written as `YYYY-MM-DD`. Numbers therefore export formatted (`$52,000`) unless you give an `exportValue`. To decide a column's value yourself, add `exportValue`:
+
+```tsx
+{
+  field: "status",
+  exportValue: (value) => String(value).toUpperCase(),          // ACTIVE
+}
+{
+  field: "salary",
+  valueFormatter: (v) => `$${v.toLocaleString()}`,              // shown as $52,000
+  exportValue: (v) => v,                                        // exported as 52000, so a spreadsheet can add it up
+}
+```
+
+The file starts with a byte-order mark so Excel reads accents and non-Latin text correctly. Commas, quotes and line breaks inside values are quoted.
+
+**The API.** Pass a ref as `apiRef` to call methods from outside the grid:
+
+```tsx
+const api = useRef<DataGridApi<Employee> | null>(null);
+
+<DataGrid apiRef={api} rowSelection ... />
+
+api.current?.exportCsv({ filename: "selected", scope: "selected" });   // download
+const text = api.current?.getCsv();                                     // the CSV as a string
+```
+
+| Method | Does |
+| --- | --- |
+| `getCsv(options?)` | Returns the CSV text without downloading it |
+| `exportCsv(options?)` | Downloads a CSV file |
+| `getSelectedRows()` | The selected row objects |
+| `getSelectedRowIds()` | The selected ids |
+| `selectAll()` | Selects every selectable row matching the search and filters |
+| `clearSelection()` | Clears the selection |
+| `refresh()` | Runs the last query again (`serverSide` only) |
+
+**Sending the CSV somewhere else** (upload, email) instead of downloading:
+
+```tsx
+const csv = api.current!.getCsv({ scope: "selected" });
+await fetch("/api/reports", { method: "POST", headers: { "Content-Type": "text/csv" }, body: csv });
+```
+
+**Your own button** next to the built-in ones:
+
+```tsx
+<DataGrid
+  apiRef={api}
+  toolbar={<button className="rk-grid__tool-btn" onClick={() => api.current?.exportCsv({ filename: "all", includeHidden: true })}>Export everything</button>}
+  ...
+/>
+```
+
+### 6.20 Virtualization
+
+For tens of thousands of rows, switch on `virtualize`. Only the rows in (and just around) the scroll window are in the DOM; empty spacer rows stand in for the rest, so the scroll bar still reflects the full data.
+
+```tsx
+<DataGrid
+  virtualize
+  rowHeight={40}          // every row must be exactly this tall
+  maxHeight={480}         // the grid scrolls inside this height (400 if you give none)
+  overscan={8}            // extra rows drawn above and below
+  columns={columns}
+  rows={twentyThousandRows}
+  getRowId={(r) => r.id}
+  searchable
+/>
+```
+
+- **Fixed row height.** Rows are laid out as `rowHeight` pixels each and cell text does not wrap (long text is cut off). Set `rowHeight` to fit your content.
+- Use it without `pagination` so everything scrolls in one list. Sorting, search and filters still work on the whole data set.
+- Row animation is skipped while virtualizing, because rows come and go as you scroll.
+- Keyboard navigation, selection and editing all work. Moving focus to a row outside the window scrolls it into view first.
+- Choose a `rowHeight` that suits your padding: 40 is right for the default cell padding.
+
+```tsx
+// 50,000 rows, searchable, selectable, keyboard friendly
+<DataGrid virtualize rowHeight={36} maxHeight="70vh" searchable rowSelection keyboardNavigation theme="graphite" ... />
+```
+
+### 6.21 Accessibility
+
+- The table has `role="grid"`. Sortable headers are focusable, expose `aria-sort`, and work with Enter and Space. Columns that are not sortable are not focus stops.
+- Editable cells are focusable (`tabindex="0"`). With `keyboardNavigation` the body has a single tab stop and arrow keys move between cells ([6.18](#618-keyboard)).
+- The search box, filter indicators (`aria-haspopup="dialog"`, `aria-expanded`), filter popups (`role="dialog"`), the Columns menu, editors, page buttons and page-size menu have `aria-label`s. Filter inputs are named after their column ("Minimum Budget", "Due from"). Checkboxes in columns with an empty header are named after the field.
+- Selected rows have `aria-selected="true"`. Row checkboxes are named "Select row N", and the header one "Select all rows".
+- The "N selected" count is a status region (`role="status"`).
+- While loading, the grid has `aria-busy="true"` and the placeholder rows are hidden from assistive technology. The error message has `role="alert"`.
 - Invalid editors set `aria-invalid="true"`.
-- Custom components you supply are responsible for their own accessibility.
+- The shimmer and row animations stop when the system has "reduce motion" turned on.
+- Custom components you supply (renderers, editors, skeleton rows, indicators) are responsible for their own accessibility.
 
-### 6.14 TypeScript
+### 6.22 TypeScript
 
 All types are exported:
 
 ```ts
 import type {
-  ColumnDef,
-  DataGridProps,
-  CellParams,
-  CellEditEvent,
-  CellEditorProps,
-  HeaderRendererProps,
-  FilterRendererProps,
-  GridSlot,
-  SortModel,
-  SortDirection,
-  MoveDirection,
-  PaginationPosition,
-  CellEditableParams,
-  ColumnCheckboxOptions,
-  FilterIndicatorProps,
-  FieldPath,
-  GridTheme,
-  CheckboxProps,
-  CheckboxVariant,
-  CheckboxSlot,
+  // grid and columns
+  DataGridProps, ColumnDef, DataGridApi, GridTheme, GridSlot, FieldPath,
+  // cells, editors, headers
+  CellParams, CellEditEvent, CellEditorProps, CellEditableParams, HeaderRendererProps, MoveDirection,
+  // sorting, paging
+  SortModel, SortDirection, PaginationPosition,
+  // filters
+  FilterType, FilterValue, FilterOption, NumberRangeFilter, DateRangeFilter, FilterRendererProps, FilterIndicatorProps,
+  // selection, server, export, loading
+  RowSelection, GridQuery, ExportOptions, SkeletonRowProps,
+  // checkbox
+  ColumnCheckboxOptions, CheckboxProps, CheckboxVariant, CheckboxSlot,
 } from "react-gridix";
 ```
 
@@ -948,14 +1821,45 @@ Typing tips:
 ```tsx
 const columns: ColumnDef<Employee>[] = [ ... ];       // field is checked against Employee (dot paths too)
 function Cell({ row }: CellParams<Employee>) { ... }   // row is typed as Employee
+
+const api = useRef<DataGridApi<Employee> | null>(null);           // typed apiRef
+const [sel, setSel] = useState<RowSelection<Employee>>({ ids: [], rows: [] });
+const [filters, setFilters] = useState<Record<string, FilterValue>>({});
+
+// narrowing a filter value yourself (for example when building a server query)
+function toParams(f: Record<string, FilterValue>) {
+  return Object.entries(f).map(([field, v]) => {
+    if (typeof v === "string") return `${field}~${v}`;                 // text / exact
+    if (Array.isArray(v)) return `${field}=${v.join(",")}`;            // select
+    if ("min" in v || "max" in v) return `${field}:${(v as NumberRangeFilter).min ?? ""}..${(v as NumberRangeFilter).max ?? ""}`;
+    return `${field}:${(v as DateRangeFilter).from ?? ""}..${(v as DateRangeFilter).to ?? ""}`;   // date
+  });
+}
 ```
 
-### 6.15 Recipes
+### 6.23 Recipes
 
 **Read-only grid**
 
 ```tsx
-<DataGrid columns={columns} rows={rows} />   // editable defaults to false
+<DataGrid columns={columns} rows={rows} />   // editable, sortable, searchable... all default to off
+```
+
+**A typical admin table**
+
+```tsx
+<DataGrid
+  columns={columns}              // sortable / filterable chosen per column
+  rows={rows}
+  getRowId={(r) => r.id}
+  searchable
+  pagination
+  rowSelection
+  columnMenu
+  exportable={{ filename: "users" }}
+  striped
+  theme="lavender"
+/>
 ```
 
 **Currency column that accepts "$1,200" when typed**
@@ -965,6 +1869,7 @@ function Cell({ row }: CellParams<Employee>) { ... }   // row is typed as Employ
   field: "salary",
   type: "number",
   align: "right",
+  sortable: true,
   valueFormatter: (v) => (v == null ? "" : money.format(v)),
   valueParser: (text) => Number(text.replace(/[$,]/g, "")),
   validate: (v) => Number.isFinite(v),
@@ -988,7 +1893,7 @@ function Cell({ row }: CellParams<Employee>) { ... }   // row is typed as Employ
 **Scrolling grid with sticky header**
 
 ```tsx
-<DataGrid pagination={false} maxHeight="60vh" />
+<DataGrid maxHeight="60vh" ... />
 ```
 
 **Highlight a row based on its data**
@@ -997,47 +1902,179 @@ function Cell({ row }: CellParams<Employee>) { ... }   // row is typed as Employ
 <DataGrid rowClassName={(row) => (row.overdue ? "bg-red-50" : "")} />
 ```
 
-### 6.16 Known limitations
+**Overdue dates in red**
+
+```tsx
+{
+  field: "due",
+  type: "date",
+  cellStyle: ({ value }) => (value && String(value) < new Date().toISOString().slice(0, 10) ? { color: "#dc2626" } : {}),
+}
+```
+
+**Status as a coloured badge, with an exact filter**
+
+```tsx
+const Badge = ({ value }: CellParams<Task>) => <span className={`badge badge-${value}`}>{String(value)}</span>;
+
+{ field: "status", sortable: true, filterable: true, filterType: "select", cellRenderer: Badge }
+```
+
+**Delete the selected rows**
+
+```tsx
+const [rows, setRows] = useState(initial);
+const [ids, setIds] = useState<(string | number)[]>([]);
+
+<button disabled={!ids.length} onClick={() => { setRows((r) => r.filter((x) => !ids.includes(x.id))); setIds([]); }}>
+  Delete {ids.length}
+</button>
+<DataGrid rows={rows} columns={columns} getRowId={(r) => r.id} rowSelection selectedRowIds={ids} onSelectionChange={(s) => setIds(s.ids)} />
+```
+
+**Bulk edit the selected rows** (`onRowsChange` gives the whole array back):
+
+```tsx
+const markDone = () => setRows((rs) => rs.map((r) => (ids.includes(r.id) ? { ...r, status: "done" } : r)));
+```
+
+**Choose the page size once and remember it**
+
+```tsx
+<DataGrid pagination pageSize={Number(localStorage.getItem("ps")) || 25} onPageSizeChange={(n) => localStorage.setItem("ps", String(n))} />
+```
+
+**A fast, big, read-only table**
+
+```tsx
+<DataGrid virtualize rowHeight={32} maxHeight="80vh" animateRows={false} searchable columns={columns} rows={hugeArray} getRowId={(r) => r.id} />
+```
+
+**An infinite-looking server table with a dark theme**
+
+```tsx
+<DataGrid serverSide pagination searchable multiSort theme="aurora" columns={columns} rows={rows} rowCount={total} onQueryChange={load} />
+```
 
-Not included (yet):
+### 6.24 Known limitations
 
-- Column resizing, reordering, hiding or pinning
-- Row selection as its own concept (a set of selected rows with `onSelectionChange`). True/false checkbox columns, including a select-all header (`headerCheckbox`), are supported, see [Checkbox columns](#checkbox-columns-type-boolean)
-- Multi-column sorting
-- Row virtualization (very large pages render every row, so keep `pageSize` moderate)
-- Server-side sorting, filtering and paging (the grid works on the array you give it)
-- Arrow-key navigation between cells
-- Controlled search, filter or page state (only `defaultSort` and `pageSize` initial values)
+Not included:
+
+- **Column reordering** (by design)
+- Row grouping, tree data, row detail panels and column spanning
+- Infinite scroll in server mode (paging is used instead)
+- Saving column widths or visibility between visits (use `onColumnVisibilityChange` and your own storage)
+- Variable row heights while virtualizing
 
 Behaviours to be aware of:
 
-- Column filters match by substring, so `active` also matches `inactive`.
-- Only one filter popup is open at a time (opening another closes the first by its outside click).
+- Text filters match by substring (`active` also matches `inactive`). Use `filterType: "exact"` or `"select"` for exact choices.
+- Only one filter popup is open at a time.
 - Stripes and the row animation restart on every page, sort, search or filter change.
-- `defaultSort` and `pageSize` are read once, on mount. Changing them later has no effect.
-- `rows` must keep a stable identity between renders, otherwise edits are discarded (see [6.8](#68-editing)).
+- `pageSize` is read once, on mount (use `onPageSizeChange`). `defaultSort` and `defaultSelectedRowIds` are read once too: to change them later, control the state.
+- `rows` must keep a stable identity between renders, otherwise edits are discarded (see [6.9](#69-editing)).
 - `onRowClick` also fires for clicks inside a cell that is being edited.
 - A `valueParser` that returns `NaN` stores `NaN`. Add `validate: (v) => Number.isFinite(v)` to reject it.
-- Date values display with `toLocaleDateString()`. Editing a `Date` cell shows its `String()` form, so store dates as ISO strings (`"2026-11-05"`) or provide a `cellEditor`.
+- `virtualize` needs fixed-height rows. A cell with wrapped text will be cut off.
+- Pinned columns only stick when the table is wider than its container.
+- In `serverSide` mode the grid cannot export or select rows it has never loaded.
+- The browser's date picker looks different in each browser. Its language follows the browser, not `dateLocale` (which only formats the display).
+
+---
+
+## 7. Demos
+
+The repository contains a playground with one page per feature:
+
+| Demo (`#id`) | Shows |
+| --- | --- |
+| Basic (`#basic`) | Opt-in sorting, global search, per-column filter dots with popups, pagination, controlled `SortModel[]` |
+| Editing (`#editing`) | Enter-moves-down editing, Tab, validation, locked cells, `onCellEdit` |
+| Custom components (`#custom`) | `cellRenderer`, `cellEditor`, `headerRenderer`, a custom funnel `filterIndicator`, a per-column indicator style, a `filterRenderer` in the popup |
+| Checkboxes (`#checkboxes`) | Boolean columns with the three variants, an empty-label header, a custom `★` character, select-all headers, locking, styling from outside, and a standalone `Checkbox` |
+| Styling (`#styling`) | Tailwind classes and inline styles, column `className` / `style`, and `stripeColors` |
+| Pagination (`#pagination`) | Top, bottom and both, no pagination, the row animation toggle, and a **controlled page and search** grid driven by outside buttons |
+| Nested fields (`#nested`) | `contact.phone` style dot paths: editing, search, filter, sort, and proof the original data is not mutated |
+| Row selection (`#selection`) | Multiple and single modes, controlled ids, `isRowSelectable`, Shift+click ranges, select-all across pages, `apiRef.selectAll()`, a Delete button |
+| Server-side (`#server`) | A fake 237-row database with 700 ms latency: server sorting, multi-sort, search debounce, filters, paging, the loading skeleton (default and custom row), and a switch that makes the request fail so you can see the error and Retry |
+| Columns (`#columns`) | Resizing, pinned columns on both sides, the Columns menu, arrow-key navigation, CSV export with `exportValue`, multi-column sort |
+| Large data (`#large`) | 20,000 virtualized rows with search, sorting and a theme |
+| Dates and filters (`#dates`) | `type: "date"` with the date picker editor, `dateMin` / `dateMax`, a `Date`-object column, from/to, number range, select and exact filters |
+| Themes (`#themes`) | A switcher for none and all 8 themes |
+
+Run it:
+
+```bash
+npm install
+npm run dev
+```
+
+Open the URL it prints (usually `http://localhost:5173`). Link straight to a demo with the `#id` in the table. The source for each demo is in `demo/examples/`, written as small, commented, copy-paste-able files.
+
+The Styling demo loads Tailwind from its CDN, so it needs an internet connection. The rest works offline.
 
 ---
 
-## 7. Troubleshooting
+## 9. Troubleshooting
 
 | Problem | Cause and fix |
 | --- | --- |
 | Everything looks unstyled | Import `react-gridix/style.css` once in your app |
 | `theme="ocean"` does nothing | The theme CSS ships in `style.css`: make sure it is imported. The attribute `data-rk-theme` should appear on the grid root |
-| I can't find the filter input | Filters are per column: set `filterable: true` in the column definition, then click the dot in the header. The old grid-level `columnFilters` prop no longer exists |
+| Headers don't sort | Sorting is per column: add `sortable: true` to the column definition. There is no grid-level `sortable` prop any more |
+| There is no search box | Pass `searchable` |
+| There is no page info or page buttons | Pass `pagination`. Without it every row is shown and there is no footer |
+| I can't find the filter input | Filters are per column: set `filterable: true`, then click the dot in the header |
+| A date column shows `2026-11-05` instead of `Nov 5, 2026` | The column needs `type: "date"` |
+| The date picker never opens | The cell must be editable (`editable` on the grid or the column), then double-click it or press Enter / F2 |
+| The number filter popup asks for Min and Max, but I wanted text | Number columns default to a range filter. Set `filterType: "text"` |
+| Select filter lists the wrong labels | Pass `filterOptions` with `{ value, label }` pairs. `value` must equal what is stored in the row |
+| Selecting rows does nothing | Add `rowSelection`. Give the grid `getRowId` so selection survives sorting and paging |
+| The server grid asks for data twice on mount | In React StrictMode (development) effects run twice. The production build calls it once. Your handler should be safe to call repeatedly |
+| The server grid shows no skeleton | `onQueryChange` must **return** the promise (`return fetch(...)` or an `async` function). A function that starts a request and returns nothing cannot be tracked. Alternatively pass `loading` |
+| The server grid shows old rows after I changed a filter | You stored an older response last. Cancel the previous request with `AbortController` or compare a request counter |
+| Page 1 is shown after every search | By design: the page resets when search, filters, sort or page size change |
+| Resize handles do nothing | The column needs `resizable: true` |
+| Pinned columns scroll away | The columns must be wider than the container (give them `width`s), otherwise there is nothing to scroll. Give pinned columns an explicit `width` |
+| Virtualized rows look cut off or overlap | `rowHeight` is smaller than your content. Increase it, or shorten the content |
+| Virtualized grid is tiny | It scrolls inside `maxHeight` (400 if unset). Set `maxHeight` |
+| Arrow keys do nothing | Add `keyboardNavigation` and click or Tab into a cell first |
+| CSV opens with strange characters in Excel | The file has a BOM and is UTF-8. Use Excel's Data > From Text if your version ignores it |
+| CSV shows `$52,000` where I wanted `52000` | Add `exportValue: (v) => v` to the column |
 | Type error on `field: "contact.phone"` | The path must exist in your row type (optional objects are fine). If `rows` is typed loosely (`any`), type the columns as `ColumnDef<Person>[]` |
 | My checkbox column header is empty | By design: boolean columns default to no label. Set `headerName` to show one |
-| No row animation | `animateRows` is off, or the system has "reduce motion" turned on |
+| No row animation | `animateRows` is off, `virtualize` is on, or the system has "reduce motion" turned on |
 | My Tailwind class doesn't change the grid | Put it in the right slot (`classNames.headerCell`, and so on). The library CSS has zero specificity, so a class in the right place wins |
 | Edits disappear on the next render | `rows` gets a new identity every render. Keep it in `useState` or `useMemo` |
-| A custom editor or renderer loses focus or resets while typing | The component is defined inline inside render. Move it to module level |
+| A custom editor, renderer or skeleton loses focus or resets while typing | The component is defined inline inside render. Move it to module level |
 | Typing in a custom editor column doesn't start editing | By design: custom editors open with double-click, Enter or F2 |
 | Enter doesn't move to the next row | The cell below is locked, you are on the last row of the page, or `enterMovesDown` is `false` |
-| Filtering "active" also shows "inactive" | Filters are substring matches. Use a `filterRenderer` with distinct values or different display text |
-| Changing `pageSize` or `defaultSort` after mount does nothing | They are initial values only |
+| Changing `pageSize` or `defaultSort` after mount does nothing | They are initial values only. Control `page` / `sort` instead |
 | A checkbox in a boolean column is greyed out and won't toggle | The cell isn't editable. Set `editable` on the grid, or `editable: true` on that column |
 | Type error: `field` not assignable | `field` must be a key of your row type. Check the spelling, and that `ColumnDef<T>` uses the same `T` as `rows` |
+
+---
+
+## 10. Migrating from the earlier version
+
+Three defaults changed so that every feature is opt-in.
+
+| Before | Now | What to do |
+| --- | --- | --- |
+| Grid prop `sortable` (default `true`), column `sortable` override | **Column** `sortable` only, default `false`. The grid-level prop is gone | Add `sortable: true` to each column that should sort. Remove `sortable` / `sortable={false}` from the grid |
+| `defaultSort` / `onSortChange` used one `SortModel` or `null` | `defaultSort` takes one `SortModel` **or an array**. `onSortChange` receives an **array** (empty when unsorted) | Change `(sort) => sort?.field` to `(sort) => sort[0]?.field` |
+| `searchable` default `true` | Default `false` | Add `searchable` to grids that should show the search box |
+| `pagination` default `true` | Default `false`. With it off there is no footer and no row count | Add `pagination` to grids that should page |
+| Filters were text only | Filter kinds: text, exact, number, date, select | Nothing to change. Number columns now get a Min / Max popup, boolean columns a checkbox list |
+| `FilterRendererProps` | Unchanged (`value: string`) | |
+
+A quick way to get the old behaviour everywhere:
+
+```tsx
+// before: <DataGrid columns={columns} rows={rows} />
+const withSorting = (cols: ColumnDef<Row>[]) => cols.map((c) => ({ sortable: true, ...c }));
+
+<DataGrid columns={withSorting(columns)} rows={rows} searchable pagination />
+```
+
+Everything else in this document is new and optional.