react-gridix 0.2.2 → 0.2.4

package/README.md

@@ -1,6 +1,6 @@
-# react-gridix
+# react-gridix Documentation
 
-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.
+A React `DataGrid` with row selection, server-side mode, typed per-column filters, date columns, in-cell editing, resizing and pinning, virtualization, export to CSV / Excel / JSON / PDF, 12 row animations, filter comparisons and 8 themes, plus the `Checkbox` it uses.
 
 **Contents**
 
@@ -11,10 +11,7 @@ A React `DataGrid` with row selection, server-side mode, typed per-column filter
 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)
-10. [Migrating from the earlier version](#10-migrating-from-the-earlier-version)
-
+8. [Troubleshooting](#8-troubleshooting)
 ---
 
 ## 1. Overview
@@ -46,6 +43,11 @@ A React `DataGrid` with row selection, server-side mode, typed per-column filter
 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**.
 
 ---
+![react-gridix ui](images/data-smaple-ui.PNG)
+
+![react-gridix ui](images/Capture.PNG)
+
+![react-gridix ui](images/Capture1.PNG)
 
 ## 2. Installation
 
@@ -63,6 +65,15 @@ import "react-gridix/style.css";
 
 The library does not inject CSS by itself. If the grid looks unstyled, this import is missing.
 
+**Optional: PDF export.** CSV, Excel (`.xlsx`) and JSON export need nothing extra. PDF export uses three small libraries that are loaded only when someone exports a PDF, so install them only if you use it:
+
+```bash
+npm install jspdf jspdf-autotable        # the PDF itself and its table
+npm install html2canvas                  # only if the PDF header / footer is a React element (it is drawn to a picture)
+```
+
+Without them, a PDF export reports an error that names the missing package (see `onExportError`) and everything else keeps working.
+
 ---
 
 ## 3. Quick start
@@ -398,6 +409,7 @@ The grid is generic: `DataGrid<T>` infers `T` from `rows`, and `ColumnDef<T>` ch
 | `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 |
+| `showFooter` | `boolean` | `true` | Set `false` to remove the footer completely (both bars), even with `pagination` on. Rows are still paged, so control the page with `page` / `onPageChange`. See [removing the toolbar and footer](#removing-the-toolbar-and-footer) |
 | `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) |
@@ -427,7 +439,8 @@ The grid is generic: `DataGrid<T>` infers `T` from `rows`, and `ColumnDef<T>` ch
 | `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 |
+| `exportable` | `boolean \| ExportOptions` | `false` | Show an export button in the toolbar. `true` gives "Export CSV"; `{ formats: ["csv", "xlsx", "json", "pdf"] }` gives an "Export" menu. See [6.19](#619-export-and-the-api) |
+| `onExportError` | `(error: Error, format: ExportFormat) => void` | | Called when an export fails (for example `jspdf` is not installed). Without it the error is logged to the console |
 | `apiRef` | `MutableRefObject<DataGridApi<T> \| null>` | | Call `exportCsv()`, `getSelectedRows()` and more from outside |
 
 **Look and feel**
@@ -436,11 +449,18 @@ The grid is generic: `DataGrid<T>` infers `T` from `rows`, and `ColumnDef<T>` ch
 | --- | --- | --- | --- |
 | `theme` | `GridTheme \| string` | | Applies a theme. Nothing changes without it. See [Theming](#4-theming) |
 | `toolbar` | `ReactNode` | | Extra content on the right of the toolbar |
+| `showToolbar` | `boolean` | `true` | Set `false` to remove the toolbar row completely (search box, Columns, Export, selected count and your `toolbar`), even when those features are on |
 | `emptyMessage` | `ReactNode` | `"No rows to show"` | Shown when no rows match |
+| `emptyComponent` | `ComponentType<EmptyStateProps<T>>` | | Your own component shown instead of `emptyMessage`. Receives `{ reason, search, filters, columns, clearAll }`. See [6.26](#626-custom-empty-state) |
+| `sortIndicator` | `"default" \| "arrow" \| ComponentType<SortIndicatorProps<T>>` | `"default"` | The arrow in sortable headers. See [6.25](#625-sort-indicator) |
 | `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) |
-| `rowAnimationClassName` | `string \| (row, rowIndex) => string` | | Your own CSS class for the entrance animation. Replaces the built-in slide-up. See [custom row animation](#custom-row-animation) |
+| `animateRows` | `boolean` | `true` | Rows animate in when they appear and out when they leave. See [row animation](#row-animation) |
+| `rowAnimation` | `RowAnimationName \| { enter?, exit? }` | `"slide-up"` | Which of the 12 built-in animations to use (`"fade"`, `"zoom"`, `"flip-x"`, ...), for both directions or `{ enter, exit }` |
+| `rowAnimationDuration` | `number` | `380` | Milliseconds an entrance takes (an exit takes 80% of it) |
+| `rowAnimationStagger` | `number` | `28` | Milliseconds between rows that appear together. `0` starts them all at once |
+| `rowExitAnimationClassName` | `string \| (row, rowIndex) => string` | | Your own CSS class for rows that leave, like `rowAnimationClassName` is for rows that arrive |
+| `rowAnimationClassName` | `string \| (row, rowIndex) => string` | | Your own CSS class for the entrance animation. Replaces the built-in one. See [custom row animation](#custom-row-animation) |
 | `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 |
@@ -479,6 +499,9 @@ const columns: ColumnDef<Employee>[] = [
 | `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 |
+| `filterOperators` | `boolean \| TextFilterOperator[]` | Adds a drop-down to the text filter popup: contains, does not contain, equals, not equal, starts with, ... Off by default (the column then always means "contains"). See [6.24](#624-filter-comparisons) |
+| `filterOperator` | `TextFilterOperator` | The comparison selected first when `filterOperators` is on. Default `"contains"` |
+| `sortIndicator` | `"default" \| "arrow" \| Component` | Overrides the grid's `sortIndicator` for this column |
 | `filterDebounce` | `number` | Milliseconds to wait after typing in **this** column's text / exact / number filter before it is applied. Overrides the grid's `filterDebounce` (default 300). `0` applies on every keystroke |
 | `filterIndicator` | `ComponentType<FilterIndicatorProps<T>>` | Your own component drawn instead of the default dot |
 | `filterIndicatorClassName` / `filterIndicatorStyle` | `string` / `CSSProperties` | Classes and inline styles for this column's indicator button |
@@ -789,6 +812,7 @@ const columns: ColumnDef<Task>[] = [
 
 - Click a day to save it at once. **Today** picks today and **Clear** saves an empty date (`null`).
 - Or type the date as `YYYY-MM-DD`. The calendar follows what you type, and Enter (or a click elsewhere) saves it. Tab saves and moves on, Escape cancels.
+- **Keys while the text box has focus:** Up / Down move the date a week, Ctrl (or Alt) + Left / Right move it a day, Page Up / Page Down move it a month. The text box and the calendar update together, and Enter saves. Plain Left / Right still move the text cursor. (Arrow-key movement *between cells* is a separate opt-in: `keyboardNavigation`.)
 - The arrows change month (`‹ ›`) and year (`« »`). Days before `dateMin` or after `dateMax` are dimmed and cannot be picked.
 - Text that is not a real date (such as `2026-02-31`) marks the editor invalid and is not saved. Clicking away from it throws it away.
 - Typing letters does not start an editor on a date cell: use double-click, Enter or F2.
@@ -879,6 +903,41 @@ The toolbar row is drawn when at least one of `searchable`, `columnMenu`, `expor
 toolbar={<button className="rg-grid__tool-btn" onClick={refetch}>Reload</button>}
 ```
 
+#### Removing the toolbar and footer
+
+Both bars are drawn automatically: the **toolbar** when `searchable`, `columnMenu`, `exportable` or `toolbar` is used, and the **footer** when `pagination` is on. To remove one completely, even though its feature is on, switch it off:
+
+```tsx
+<DataGrid showToolbar={false} showFooter={false} ... />
+```
+
+The features keep working, so you can drive them yourself:
+
+```tsx
+const api = useRef<DataGridApi<Person> | null>(null);
+const [search, setSearch] = useState("");
+const [page, setPage] = useState(0);
+
+// your own search box and pager, with the grid's bars removed
+<input value={search} onChange={(e) => setSearch(e.target.value)} placeholder="Search…" />
+<button onClick={() => api.current?.exportCsv({ filename: "people" })}>Export</button>
+<button disabled={page === 0} onClick={() => setPage(page - 1)}>Previous</button>
+<button onClick={() => setPage(page + 1)}>Next</button>
+
+<DataGrid
+  apiRef={api}
+  searchable showToolbar={false}                 // the search still filters, from `search`
+  pagination pageSize={10} showFooter={false}    // still 10 rows per page, from `page`
+  search={search} onSearchChange={setSearch}
+  page={page} onPageChange={setPage}
+  exportable showToolbar={false}
+  columns={columns}
+  rows={rows}
+/>
+```
+
+Remember the "N selected" count lives in the toolbar and the footer, so read the selection from `onSelectionChange` instead when both are removed. Each bar can be removed on its own: `showToolbar={false}` leaves the footer, `showFooter={false}` leaves the toolbar.
+
 ### 6.9 Editing
 
 Turn editing on with `editable` on the grid, then lock or unlock columns:
@@ -1197,7 +1256,9 @@ 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) |
+| `toolButton` | Toolbar buttons (Columns, Export, Retry) |
+| `exportMenu` | The "Export" button when several formats are offered (in addition to `toolButton`) |
+| `sortIndicator` | The wrapper of the arrow in a sortable header |
 | `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 |
@@ -1267,28 +1328,59 @@ Rows alternate between the two colours, starting with the first. `stripeColors`
 
 #### Row animation
 
-When rows render (the first load, a new page, a sort, a search or a filter), they slide up and fade in, one after another. It is on by default.
+Rows animate when they appear and when they leave. It is on by default (a slide up, and a slide up and fade out). The important part is that **rows are matched by their id (`getRowId`)**, so the grid never replays the animation on rows that stay:
+
+- A **new row** adds itself to the list with the "in" animation, while every other row stays exactly where it is.
+- A **removed row** (deleted, or hidden by a search or filter) stays on screen for a moment, plays the "out" animation where it was, then goes. The rows around it do not move until it is gone.
+- Changing the **page** (or the page size) replaces the rows at once with the "in" animation: it would be odd to show the old page leaving.
+- Sorting moves rows without animating them.
 
 ```tsx
-<DataGrid animateRows={false} />        // turn it off
+<DataGrid animateRows={false} />                                         // turn it off
+<DataGrid rowAnimation="zoom" />                                         // zoom in, zoom out
+<DataGrid rowAnimation={{ enter: "slide-left", exit: "fade" }} />        // mix the two directions
+<DataGrid rowAnimation={{ enter: "bounce", exit: "none" }} />            // "none": rows just disappear
+<DataGrid rowAnimation="flip-x" rowAnimationDuration={600} rowAnimationStagger={60} />
 ```
 
-Tune it with `--rg-row-duration` (default `0.38s`) and `--rg-row-stagger` (default `28ms` per row, up to 24 rows). Changing page or sort also scrolls the grid's own scroll area smoothly back to the top. Visitors who ask their system for reduced motion get no animation (`prefers-reduced-motion`).
+The built-in animations (each has an "in" and an "out" version):
+
+| Name | In | Out |
+| --- | --- | --- |
+| `"fade"` | fades in | fades out |
+| `"slide-up"` (default) | rises from below | floats up |
+| `"slide-down"` | drops from above | sinks down |
+| `"slide-left"` | slides in from the left | slides out to the left |
+| `"slide-right"` | slides in from the right | slides out to the right |
+| `"zoom"` | grows from small | shrinks away |
+| `"flip-x"` | flips up around its horizontal axis | flips away |
+| `"flip-y"` | swings in around its vertical axis | swings out |
+| `"rotate"` | turns and scales in | turns and scales out |
+| `"skew"` | slides in leaning over | slides out leaning over |
+| `"blur"` | comes into focus | blurs away |
+| `"bounce"` | drops in and bounces | hops and jumps out |
+| `"none"` | no animation | removed at once |
+
+Use a row id that does not change: `getRowId={(row) => row.id}`. Without it the grid uses the row's position as its id, and removing a row from the middle makes every row after it look different, so the wrong row animates out.
+
+Tuning: `rowAnimationDuration` (default 380 ms; exits take 80%), `rowAnimationStagger` (default 28 ms between rows that appear together, up to 24 rows). The same values exist as CSS variables on the grid: `--rg-row-duration`, `--rg-row-exit-duration` and `--rg-row-stagger`, so you can also set them in your own CSS. Visitors who ask their system for reduced motion get no animation, and rows leave at once. Animation is also off while `virtualize` is on.
 
 #### Custom row animation
 
-Pass your own CSS class to replace the built-in slide-up. The class should set `animation`. Every row also gets the CSS variable `--rg-i` (its position on the page, 0 to 24), so a delay of `calc(var(--rg-i) * 40ms)` makes rows arrive one after another.
+Pass your own CSS class to replace the built-in animation: `rowAnimationClassName` for rows that arrive and `rowExitAnimationClassName` for rows that leave. The class should set `animation`; an exit class should end in the hidden state and keep it (`forwards`). Every row also gets the CSS variable `--rg-i` (its position among the rows that appear or leave together, 0 to 24), so a delay of `calc(var(--rg-i) * 40ms)` makes rows come one after another.
 
 ```css
 @keyframes fade-left { from { opacity: 0; transform: translateX(-24px); } to { opacity: 1; transform: none; } }
-.row-fade-left { animation: fade-left 0.45s ease-out both; animation-delay: calc(var(--rg-i, 0) * 45ms); }
+@keyframes fade-right { to { opacity: 0; transform: translateX(24px); } }
+.row-fade-left  { animation: fade-left 0.45s ease-out both; animation-delay: calc(var(--rg-i, 0) * 45ms); }
+.row-fade-right { animation: fade-right 0.3s ease-in forwards; }
 ```
 
 ```tsx
-<DataGrid rowAnimationClassName="row-fade-left" ... />
+<DataGrid rowAnimationClassName="row-fade-left" rowExitAnimationClassName="row-fade-right" ... />
 ```
 
-It can also be a function of the row, for example to animate new rows differently:
+Both can be functions of the row, for example to flash new rows:
 
 ```tsx
 <DataGrid rowAnimationClassName={(row) => (row.isNew ? "row-flash" : "row-fade-left")} ... />
@@ -1296,9 +1388,41 @@ It can also be a function of the row, for example to animate new rows differentl
 
 With Tailwind, define the keyframes in your config and use the utility, for example `rowAnimationClassName="animate-fade-in-left [animation-delay:calc(var(--rg-i)*40ms)]"`.
 
-- It runs on the same moments as the built-in animation: first render, a new page, sort, search or filter.
-- `animateRows={false}` turns every row animation off, custom or not. It is also skipped while `virtualize` is on.
-- Reduced motion: the built-in animation stops for people who ask for it. Your own class is yours to handle: wrap it in `@media (prefers-reduced-motion: no-preference) { ... }`.
+- A custom class replaces the built-in animation of its direction only: you can customise just the entrance and keep the built-in exit, or the reverse.
+- A leaving row is removed when its animation ends (or after 2.5 seconds if your class has none).
+- `animateRows={false}` turns every row animation off, custom or not.
+- Reduced motion: the built-in animations stop for people who ask for it. Your own class is yours to handle: wrap it in `@media (prefers-reduced-motion: no-preference) { ... }`.
+
+#### What does `classNames={{ cell: "border border-teal-400 py-2" }}` do?
+
+`classNames` adds your own CSS classes to named parts of the grid. The key is the part (a **slot**), and the value is the class string. `cell` is the slot for **every body cell** (`<td>`) in every column. So this:
+
+```tsx
+<DataGrid classNames={{ cell: "border border-teal-400 py-2" }} ... />
+```
+
+adds those three Tailwind classes to each body cell:
+
+| Class | Effect |
+| --- | --- |
+| `border` | A 1px border on all four sides of every cell, drawn on top of the grid's normal line under each row (`border-collapse` merges neighbouring borders into a grid of lines) |
+| `border-teal-400` | Makes that border teal |
+| `py-2` | Vertical padding of 0.5rem (8px) top and bottom, replacing the default 9px. The horizontal padding (12px) is unchanged |
+
+It works with no `!important` because the library's own CSS has zero specificity, so any class you add wins. The header cells are not affected (use `classNames.headerCell`), and neither is a single column (use that column's `cellClassName`, see below). The inline-style twin is `styles`: `styles={{ cell: { border: "1px solid #2dd4bf", paddingBlock: 8 } }}`.
+
+Other slots work the same way: `root`, `toolbar`, `search`, `table`, `thead`, `headerRow`, `headerCell`, `tbody`, `row`, `cell`, `editor`, `empty`, `footer`, and so on (the full list is in the slot table below).
+
+**Where each kind of class goes**
+
+| You want to style | Use |
+| --- | --- |
+| Every body cell | `classNames.cell` / `styles.cell` |
+| Every header cell | `classNames.headerCell` / `styles.headerCell` |
+| Whole rows, or some rows | grid `rowClassName` / `rowStyle` (a string or a function of the row) |
+| One column (header and cells) | column `className` / `style` |
+| One column's body cells | column `cellClassName` / `cellStyle` (a string or a function of the cell) |
+| One column's header | column `headerClassName` / `headerStyle` |
 
 #### Width
 
@@ -1439,7 +1563,7 @@ const [current, setCurrent] = useState<Person | null>(null);
 {current && <PersonDetails person={current} />}
 ```
 
-**From outside the grid**, with `apiRef` (see [6.19](#619-csv-export-and-the-api)):
+**From outside the grid**, with `apiRef` (see [6.19](#619-export-and-the-api)):
 
 ```tsx
 const api = useRef<DataGridApi<Person> | null>(null);
@@ -1636,7 +1760,7 @@ api.current?.refresh();
 
 **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.
+- Selection, [CSV export of selected rows](#619-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.
@@ -1790,7 +1914,7 @@ With `virtualize`, moving past the visible window scrolls the target row into vi
 
 Without `keyboardNavigation`, cells are reachable with Tab (editable cells) or the mouse, as before.
 
-### 6.19 CSV export and the API
+### 6.19 Export and the API
 
 **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).
 
@@ -1801,12 +1925,146 @@ Without `keyboardNavigation`, cells are reachable with Tab (editable cells) or t
 <DataGrid exportable={{ scope: "selected" }} rowSelection ... />               // only the selected rows
 ```
 
+**More formats: Excel, JSON and PDF.** List the formats you want and the button becomes an "Export" menu:
+
+```tsx
+<DataGrid
+  rowSelection
+  pagination
+  exportable={{ filename: "employees", formats: ["csv", "xlsx", "json", "pdf"] }}
+  columns={columns} rows={rows} getRowId={(r) => r.id}
+/>
+```
+
+The menu has two parts. **Rows to export** lets the user pick *Visible rows* (what is on screen: the current page), *All matching rows* (every page; only offered with `pagination`) or *Selected rows* (only offered with `rowSelection`, and disabled while nothing is selected). Each choice shows how many rows it covers. **Download as** has one button per format. The menu remembers the last choice. With a single format (the default `["csv"]`) you get the plain "Export CSV" / "Export Excel" / "Export JSON" / "Export PDF" button instead, using `scope` from `exportable`.
+
+| Format | What you get | Needs |
+| --- | --- | --- |
+| `"csv"` | Text of the displayed values, opens in any spreadsheet | nothing |
+| `"xlsx"` | A real Excel workbook: bold coloured header row that stays in place while you scroll, auto-filter, sized columns, real numbers, real dates and real booleans | nothing (written by the library itself) |
+| `"json"` | An array of objects, one per row, with real numbers and booleans and ISO dates (`"2026-11-05"`) | nothing |
+| `"pdf"` | A paged table with an optional title, header, footer and "Page 1 of 3" | `jspdf` and `jspdf-autotable` (and `html2canvas` for a header / footer element) |
+
+The same exports are available from code, for your own buttons:
+
+```tsx
+const api = useRef<DataGridApi<Employee> | null>(null);
+<DataGrid apiRef={api} rowSelection ... />
+
+api.current?.exportXlsx({ scope: "selected", filename: "picked", sheetName: "Picked" });
+api.current?.exportJson({ scope: "visible", jsonKeys: "header", jsonIndent: 0 });
+await api.current?.exportPdf({ scope: "filtered", pdf: { title: "All employees" } });
+await api.current?.exportAs("csv", { scope: "page" });          // any format by name
+
+const json: string = api.current!.getJson({ scope: "filtered" });       // build without downloading
+const blob: Blob = await api.current!.getXlsx();                        // e.g. upload it to your server
+const pdf: Blob = await api.current!.getPdf();
+const csv: string = api.current!.getCsv();
+```
+
+`exportXlsx` and `exportPdf` return promises. They **reject** when something goes wrong (a missing library, for instance), so `try / catch` them in your own code. The toolbar menu catches errors for you and sends them to `onExportError`:
+
+```tsx
+<DataGrid
+  onExportError={(error, format) => toast.error(`${format} export failed: ${error.message}`)}
+  exportable={{ formats: ["csv", "pdf"] }}
+/>
+```
+
+**Which rows.** `scope` accepts `"filtered"` (default), `"visible"` or `"page"` (the same: the rows on screen) and `"selected"`. A page export continues the row numbers of a `sequence` column (page 2 starts at 11) unless the column has `sequenceRestartEachPage`.
+
+**What each format writes.** CSV and PDF write the displayed text (`valueFormatter` applied, `Yes` / `No` for booleans, dates as `YYYY-MM-DD`). Excel and JSON write real values: a number column stays a number (`52000`, not `"$52,000"`), a boolean column stays `true` / `false`, a date column is a real Excel date, a column with a `valueFormatter` that changes text (for example codes shown as names) writes the shown text. A column's `exportValue(value, row)` overrides all of this in every format.
+
+#### PDF header and footer
+
+`pdf.header` and `pdf.footer` accept **a string or a React element**, and appear on every page.
+
+```tsx
+// A string. {page}, {pages} and {date} are replaced on each page.
+<DataGrid
+  exportable={{
+    formats: ["pdf"],
+    pdf: {
+      title: "Employee list",
+      header: "Acme Corporation, People report ({date})",
+      footer: "Confidential, page {page} of {pages}",
+    },
+  }}
+/>
+```
+
+```tsx
+// A component: a logo, colours, borders, anything you can style. Images and inline styles work.
+import logo from "./logo.png";
+
+<DataGrid
+  exportable={{
+    formats: ["pdf"],
+    pdf: {
+      header: (
+        <div style={{ display: "flex", alignItems: "center", gap: 12, borderBottom: "3px solid #4f46e5", paddingBottom: 6 }}>
+          <img src={logo} alt="" width={40} height={40} style={{ borderRadius: 8 }} />
+          <div>
+            <div style={{ fontSize: 20, fontWeight: 700, color: "#312e81" }}>Acme Corporation</div>
+            <div style={{ fontSize: 12, color: "#6b7280" }}>People &amp; Culture report</div>
+          </div>
+        </div>
+      ),
+      footer: <div style={{ textAlign: "center", fontSize: 11, color: "#6b7280" }}>Confidential. Do not share.</div>,
+    },
+  }}
+/>
+```
+
+An element is drawn off-screen, turned into a picture with `html2canvas`, and placed on each page, shrunk to fit the page width and `maxImageHeight` (default 90 pt) with its proportions kept. A few things to know about elements:
+
+- They fill the page width, so lay them out with `display: flex` and `justify-content` inside (the `headerAlign` / `footerAlign` options move strings, not elements).
+- They are drawn once, so they cannot show the page number. Use a string footer for "page 2 of 5", or both: an element header and a string footer.
+- Images must be loadable from the page: your own assets, data URLs, or servers that allow cross-origin use (CORS). Otherwise the browser blocks the picture.
+- Inline styles and plain CSS classes work. Very new CSS features may not be supported by `html2canvas`.
+
+Other `pdf` options:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `title` | | A heading above the table on the first page |
+| `header`, `footer` | | A string or element, on every page |
+| `headerAlign`, `footerAlign` | `"left"`, `"center"` | Where a **string** goes: `"left"`, `"center"`, `"right"` |
+| `orientation` | `"auto"` | `"portrait"`, `"landscape"`, or `"auto"` (landscape when there are more than 6 columns) |
+| `pageSize` | `"a4"` | `"a3"`, `"a4"`, `"a5"`, `"letter"`, `"legal"` |
+| `margin` | `36` | Points around the page (72 points = 1 inch) |
+| `fontSize` | `9` | Table text size in points |
+| `tableTheme` | `"striped"` | `"striped"`, `"grid"` or `"plain"` |
+| `headColor`, `headTextColor` | `"#4f46e5"`, `"#ffffff"` | Colours of the table's header row, as hex |
+| `pageNumbers` | `true` | "Page 1 of 3" in the bottom right |
+| `maxImageHeight` | `90` | Tallest header / footer picture, in points |
+| `fontName`, `beforeRender` | | Use another font (see below) |
+
+jsPDF's built-in fonts cover Western European letters. For other alphabets (Arabic, Chinese, ...) register a font in `beforeRender` and name it in `fontName`:
+
+```tsx
+pdf: {
+  fontName: "NotoSans",
+  beforeRender: (doc) => {
+    doc.addFileToVFS("NotoSans.ttf", notoSansBase64);   // your font file as base64
+    doc.addFont("NotoSans.ttf", "NotoSans", "normal");
+  },
+}
+```
+
+#### Export options
+
 | `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 |
+| `filename` | `"export"` | File name without the extension |
+| `scope` | `"filtered"` | `"filtered"` all rows matching search and filters, `"visible"` / `"page"` the rows on screen, `"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 |
+| `sanitize` | `true` | CSV only: put an apostrophe in front of text starting with `=`, `+`, `-` or `@`, so Excel does not run it as a formula |
+| `formats` | `["csv"]` | The formats the toolbar offers: any of `"csv"`, `"xlsx"`, `"json"`, `"pdf"` |
+| `sheetName` | `"Sheet1"` | Excel only: the worksheet's name |
+| `jsonKeys` | `"field"` | JSON only: use each column's `"field"` or its `"header"` text as the key |
+| `jsonIndent` | `2` | JSON only: spaces of indentation (`0` for one line) |
+| `pdf` | | PDF only: see above |
 
 **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`:
 
@@ -2063,7 +2321,132 @@ const markDone = () => setRows((rs) => rs.map((r) => (ids.includes(r.id) ? { ...
 <DataGrid serverSide pagination searchable multiSort theme="aurora" columns={columns} rows={rows} rowCount={total} onQueryChange={load} />
 ```
 
-### 6.24 Known limitations
+### 6.24 Filter comparisons
+
+A text filter normally means "contains". Switch on `filterOperators` on a column and its popup gets a drop-down on top, so the user chooses **how** to compare:
+
+| Choice | A row passes when its text... |
+| --- | --- |
+| Contains | has the typed text anywhere |
+| Does not contain | does not have it anywhere |
+| Equals | is exactly the typed text |
+| Not equal | is anything else |
+| Starts with | begins with it |
+| Does not start with | does not begin with it |
+| Ends with | ends with it |
+| Does not end with | does not end with it |
+
+All comparisons ignore upper / lower case. Changing the choice filters straight away; typing waits for `filterDebounce` as usual.
+
+```tsx
+const columns: ColumnDef<User>[] = [
+  { field: "name", filterable: true, filterOperators: true },                    // all eight
+  { field: "email", filterable: true,
+    filterOperators: ["contains", "startsWith", "endsWith", "equals"],            // only these four
+    filterOperator: "startsWith" },                                              // selected first
+  { field: "department", filterable: true },                                     // no drop-down: always "contains"
+];
+```
+
+- It is **off by default**. A column without `filterOperators` shows just the box and always means "contains" (or "equals" for `filterType: "exact"`).
+- It applies to text columns (`filterType` `"text"` or `"exact"`). It does nothing for number, date or select filters, nor when you supply your own `filterRenderer`.
+- Pass `true` for all eight, or a list to offer fewer. The list keeps the order shown above. `filterOperator` sets the first choice (default `"contains"`).
+- Keyboard: focus the drop-down, then Up / Down open it and move, Enter or Space choose, Esc closes just the list.
+
+**The filter value.** With `filterOperators` on, the column's filter is an object, not a string: `{ operator: "startsWith", value: "ann" }` (type `TextFilter`). You see it in `filters` / `onFiltersChange` (controlled mode) and in the `serverSide` query, where your API applies it:
+
+```tsx
+onQueryChange={async (query) => {
+  const nameFilter = query.filters.name;           // string, or { operator, value } when filterOperators is on
+  const { operator, value } = typeof nameFilter === "string" ? { operator: "contains", value: nameFilter } : nameFilter;
+  // ... translate to your database: operator "startsWith" -> LIKE 'value%'
+}}
+```
+
+Controlled filters work the same way, and a plain string is still accepted (it is read as "contains"):
+
+```tsx
+<DataGrid filters={{ name: { operator: "notContains", value: "test" } }} onFiltersChange={setFilters} ... />
+```
+
+### 6.25 Sort indicator
+
+The arrow in sortable headers can be changed. The default is the small text arrow (▲ ▼ ↕). Two other choices:
+
+```tsx
+<DataGrid sortIndicator="arrow" ... />                 // a smooth arrow that turns around
+<DataGrid sortIndicator={MyIndicator} ... />           // your own component
+```
+
+**`"arrow"`** is an SVG arrow. Ascending points up, descending points down, and "not sorted" is a dim up arrow. When the sort changes it **rotates smoothly** (a CSS transition of `--rg-sort-turn`, default `0.28s`, off for reduced motion). It always keeps turning the same way (up, down, back up), so each click is one clean half-turn. With several sorted columns it shows each column's priority number.
+
+**Your own component** receives `{ column, direction, priority }`: `direction` is `"asc"`, `"desc"` or `null`, and `priority` is 1, 2, ... when several columns are sorted. The grid keeps the component mounted in the same place, so a CSS `transition` on it animates between states. Define it outside any component:
+
+```tsx
+import { SortArrow, type SortIndicatorProps } from "react-gridix";
+
+// Reuse the rotating arrow with your own size and colour
+function BigArrow({ direction }: SortIndicatorProps<User>) {
+  return <SortArrow direction={direction} size={18} style={{ color: "tomato" }} />;
+}
+
+// Or draw anything, turned with CSS
+function Chevron({ direction }: SortIndicatorProps<User>) {
+  return (
+    <span style={{ display: "inline-block", transition: "transform .3s", transform: direction === "desc" ? "rotate(180deg)" : "none", opacity: direction ? 1 : 0.3 }}>
+      ⌃
+    </span>
+  );
+}
+
+<DataGrid sortIndicator={BigArrow} columns={columns} rows={rows} />
+```
+
+A single column can use its own: `{ field: "name", sortable: true, sortIndicator: "arrow" }`. The wrapper `<span>` has the `sortIndicator` slot (`classNames={{ sortIndicator: "..." }}`) and a `data-direction` attribute (`asc`, `desc` or `none`) you can style.
+
+### 6.26 Custom empty state
+
+When there are no rows to show, the grid draws `emptyMessage` (default "No rows to show"). For more than a sentence, pass a component with `emptyComponent`. It replaces the message and receives:
+
+| Prop | Meaning |
+| --- | --- |
+| `reason` | `"no-data"` when the grid was given no rows, `"no-results"` when the search or filters hide them all |
+| `search` | The search text (empty when none) |
+| `filters` | The active filters, by field |
+| `columns` | The visible columns |
+| `clearAll()` | Clears the search and all filters, which brings the rows back |
+
+```tsx
+import type { EmptyStateProps } from "react-gridix";
+
+function NothingHere({ reason, clearAll, search }: EmptyStateProps<User>) {
+  if (reason === "no-data") {
+    return (
+      <div style={{ textAlign: "center" }}>
+        <img src="/empty-box.svg" alt="" width={96} />
+        <h3>No users yet</h3>
+        <button onClick={openAddUserDialog}>Add the first user</button>
+      </div>
+    );
+  }
+  return (
+    <div style={{ textAlign: "center" }}>
+      <h3>Nothing matches{search ? ` "${search}"` : ""}</h3>
+      <button onClick={clearAll}>Clear search and filters</button>
+    </div>
+  );
+}
+
+<DataGrid emptyComponent={NothingHere} columns={columns} rows={users} />
+```
+
+- It is drawn inside one full-width table cell (class `rg-grid__empty rg-grid__empty--custom`, slot `empty`), so `classNames={{ empty: "py-10" }}` still works.
+- Define the component outside render so it keeps its identity (and its state).
+- While loading, the skeleton is shown, not this. After a failed load, the error message and Retry button are shown.
+- When rows are removed with an exit animation, the component appears once the last row has left.
+- Keep using `emptyMessage` for a plain sentence. `emptyComponent` wins when both are set.
+
+### 6.27 Known limitations
 
 Not included:
 
@@ -2086,6 +2469,9 @@ Behaviours to be aware of:
 - 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 date calendar starts weeks on Sunday and has no week numbers or time of day.
+- Excel export writes one worksheet. It does not carry the grid's colours or fonts, only a styled header row.
+- PDF text uses jsPDF's built-in Western European fonts unless you register another one (`pdf.fontName`). A PDF header / footer element is a picture: its text cannot be selected.
+- Rows that leave play their exit animation as a copy in place; the table closes the gap when the animation ends instead of sliding the rows below up.
 
 ---
 
@@ -2108,6 +2494,7 @@ The repository contains a playground with one page per feature:
 | Large data (`#large`) | 20,000 virtualized rows with search, sorting and a theme |
 | Dates and filters (`#dates`) | `type: "date"` with the calendar editor and range-calendar filter, `dateMin` / `dateMax`, a `Date`-object column, from/to, number range, select and exact filters |
 | Themes (`#themes`) | A switcher for none and all 8 themes |
+| Animations and export (`#features`) | Pick the "in" and "out" animation from 12, add and remove rows (top, end, selected, all) and watch the other rows stay put; the rotating sort arrow, the default arrow and a custom indicator component; the Export menu (CSV, Excel, JSON, PDF) with a visible / selected / all choice and a PDF header and footer given as a string or as a styled component with a logo; filter comparison drop-downs (all eight, a short list, and none); a custom empty-state component |
 
 Run it:
 
@@ -2122,6 +2509,7 @@ The Styling demo loads Tailwind from its CDN, so it needs an internet connection
 
 ---
 
+
 ## 8. Troubleshooting
 
 | Problem | Cause and fix |
@@ -2136,6 +2524,12 @@ The Styling demo loads Tailwind from its CDN, so it needs an internet connection
 | The date calendar never opens | The cell must be editable (`editable` on the grid or the column), then double-click it or press Enter / F2 |
 | A sequence column shows nothing or a type error | Give it `type: "sequence"` and a `field` that starts with `#`, for example `{ field: "#", type: "sequence" }` |
 | My custom row animation does nothing | `animateRows` is `false`, `virtualize` is on, or your class does not set `animation`. Check that the keyframes exist and that the class name is spelled the same in CSS |
+| PDF export fails with `needs the package "jspdf"` | Install the optional packages: `npm install jspdf jspdf-autotable` (and `html2canvas` for a header / footer element). Handle the error with `onExportError` |
+| The PDF header / footer element has no image | The image must be loadable by the browser without being blocked: a bundled asset, a data URL, or a server that sends CORS headers |
+| The comparison drop-down does not show in the filter popup | Add `filterOperators: true` (or a list) to that column. It applies to text columns only, and not with a custom `filterRenderer` |
+| The wrong row animates out when I delete one | Give the grid `getRowId={(row) => row.id}`. Without it rows are identified by position |
+| Removed rows do not animate | `animateRows` is off, `virtualize` is on, the exit animation is `"none"`, or the system asks for reduced motion. Rows are also replaced at once when the page changes |
+| "Selected rows" is greyed out in the export menu | Nothing is selected yet, or `rowSelection` is off |
 | The number filter popup asks for Min and Max, but I wanted text | Number columns default to a range filter. Set `filterType: "text"` |
 | A typed filter feels slow, or fires on every key | Change the wait with `filterDebounce` on the grid (default 300 ms) or on one column. Use `0` for no waiting |
 | Select filter lists the wrong labels | Pass `filterOptions` with `{ value, label }` pairs. `value` must equal what is stored in the row |
@@ -2163,28 +2557,4 @@ The Styling demo loads Tailwind from its CDN, so it needs an internet connection
 | 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` |
 
----
-
-### Changed defaults
-
-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.
+---