react-gridix 0.2.3 → 0.2.5

package/README.md

@@ -1,6 +1,6 @@
 # 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**
 
@@ -12,7 +12,6 @@ A React `DataGrid` with row selection, server-side mode, typed per-column filter
 6. [DataGrid](#6-datagrid)
 7. [Demos](#7-demos)
 8. [Troubleshooting](#9-troubleshooting)
-9. [Migrating from the earlier version](#10-migrating-from-the-earlier-version)
 
 ---
 
@@ -44,6 +43,12 @@ 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**.
 
+Demo Display
+![Drag Racing](https://raw.githubusercontent.com/felixongom/react-gridix/refs/heads/main/images/Capture1.PNG)
+![Drag Racing](https://raw.githubusercontent.com/felixongom/react-gridix/refs/heads/main/images/Capture.PNG)
+![Drag Racing](https://raw.githubusercontent.com/felixongom/react-gridix/refs/heads/main/images/data-smaple-ui.PNG)
+![Drag Racing](https://raw.githubusercontent.com/felixongom/react-gridix/refs/heads/main/images/Tailwind.PNG)
+
 ---
 
 ## 2. Installation
@@ -62,6 +67,68 @@ 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. The grid does **not** import them (so your app builds and runs without them); you install them and hand them over, ideally through a function that imports them only when someone exports a PDF:
+
+```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)
+```
+
+```tsx
+<DataGrid
+  exportable={{
+    formats: ["csv", "pdf"],
+    pdf: {
+      libraries: async () => ({
+        jsPDF: (await import("jspdf")).jsPDF,
+        autoTable: (await import("jspdf-autotable")).default,
+        html2canvas: (await import("html2canvas")).default,   // only for a header / footer element
+      }),
+    },
+  }}
+/>
+```
+Read more about stying pdf here [stying pdf here](https://github.com/simonbengtsson/jsPDF-AutoTable). Use the style property in `autoTableOptions` for styling cells
+
+Adding `Header` and  `Footer` component 
+```tsx
+import logo from "./logo.png";
+
+<DataGrid
+  columns={columns}
+  rows={rows}
+  getRowId={(r) => r.id}
+  exportable={{
+    formats: ["pdf"],
+    pdf: {
+      libraries: async () => ({
+        jsPDF: (await import("jspdf")).jsPDF,
+        autoTable: (await import("jspdf-autotable")).default,
+        html2canvas: (await import("html2canvas")).default,   // required for an element
+      }),
+
+      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>
+      ),
+    },
+  }}
+/>
+``
+
+Without `libraries`, or if an import fails, a PDF export reports an error that says what to install (see `onExportError`) and everything else keeps working.
+
 ---
 
 ## 3. Quick start
@@ -427,7 +494,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**
@@ -438,10 +506,16 @@ The grid is generic: `DataGrid<T>` infers `T` from `rows`, and `ColumnDef<T>` ch
 | `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 |
@@ -480,6 +554,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 |
@@ -1234,7 +1311,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 |
@@ -1304,28 +1383,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")} ... />
@@ -1333,9 +1443,10 @@ 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?
 
@@ -1507,7 +1618,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);
@@ -1704,7 +1815,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.
@@ -1858,7 +1969,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).
 
@@ -1869,12 +1980,299 @@ 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), given in `pdf.libraries` |
+
+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"] }}
+/>
+```
+
+To export pdf, install supporting pdf libraries
+```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)
+```
+
+```tsx
+<DataGrid
+  exportable={{
+    formats: ["csv", "pdf"],
+    pdf: {
+      libraries: async () => ({
+        jsPDF: (await import("jspdf")).jsPDF,
+        autoTable: (await import("jspdf-autotable")).default,
+        html2canvas: (await import("html2canvas")).default,   // only for a header / footer element
+      }),
+    },
+  }}
+/>
+```
+
+```tsx
+<DataGrid
+  rowSelection
+  pagination
+  columns={columns}
+  rows={rows}
+  getRowId={(r) => r.id}
+  exportable={{
+    filename: "employees",
+    formats: ["csv", "xlsx", "json", "pdf"],
+    pdf: {
+      // required for PDF (npm install jspdf jspdf-autotable html2canvas)
+      libraries: async () => ({
+        jsPDF: (await import("jspdf")).jsPDF,
+        autoTable: (await import("jspdf-autotable")).default,
+        html2canvas: (await import("html2canvas")).default,
+      }),
+
+      title: <TitleComponent />,
+      margin: { top: 60, right: 30, bottom: 50, left: 30 },
+      tableTheme: "grid",                       // "striped" | "grid" | "plain"
+
+      style: {
+        headColor: "#f59e0b",                   // header row background
+        headTextColor: "#111827",
+        stripeColors: ["#ffffff", "#f1f5f9"],   // rows alternate between these
+        bodyTextColor: "#1f2937",
+        borderColor: "#cbd5e1",
+        borderWidth: 0.4,
+        cellPadding: { top: 6, bottom: 6, left: 8, right: 8 },
+        fontSize: 10,
+        pageBackground: "#ffffff",              // try "#0f172a" for a dark page
+        columns: {                              // per column, by its field
+          salary: { fontStyle: "bold", align: "right" },
+          name: { width: 120 },
+        },
+      },
+    },
+  }}
+/>
+```
+Setting Border bottom
+```tsx
+pdf: {
+  libraries:async () => ({
+    jsPDF: (await import("jspdf")).jsPDF,
+    autoTable: (await import("jspdf-autotable")).default,
+    html2canvas: (await import("html2canvas")).default,
+  }),
+  // 
+  tableTheme: "plain",                       // plain draws no lines, so only your bottom border shows
+  autoTableOptions: {
+    styles: {
+      lineWidth: { bottom: 0.5 },            // points; only the bottom side
+      lineColor: [203, 213, 225],            // [r, g, b]
+    },
+  },
+}
+```
+Read more about stying pdf here [stying pdf here](https://github.com/simonbengtsson/jsPDF-AutoTable). Use the style property in `autoTableOptions` for styling cells
+
+
+**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: <TitleComponent />,
+      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 |
+| --- | --- | --- |
+| `libraries` | | **Required.** `{ jsPDF, autoTable, html2canvas? }` or a function returning them (see Installation) |
+| `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): a number, or `{ top, right, bottom, left }` |
+| `fontSize` | `9` | Table text size in points |
+| `tableTheme` | `"striped"` | `"striped"`, `"grid"` or `"plain"` |
+| `headColor`, `headTextColor` | `"#4f46e5"`, `"#ffffff"` | Colours of the table's header row (any CSS colour) |
+| `matchGridStyle` | `false` | Copy the grid's on-screen look into the PDF. See [PDF styling](#pdf-styling) |
+| `style` | | Colours, stripes, borders, padding, page background, per-column looks. See [PDF styling](#pdf-styling) |
+| `autoTableOptions` | | Raw options for jspdf-autotable, merged last, for anything not covered |
+| `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");
+  },
+}
+```
+
+#### PDF styling
+
+By default the PDF has its own look (indigo header, light stripes). Two ways to change it, and they combine.
+
+**1. Copy the grid's look, only when you ask.** `matchGridStyle: true` reads the grid as it is on screen when the export runs: the header's background and text colour, the text colour and size of the rows, the two stripe colours (with `striped`), the row borders, and the grid's own background (which matters for dark themes). It reads real elements, so it follows `theme`, Tailwind classes and your CSS. Without the option nothing is read.
+
+```tsx
+<DataGrid theme="midnight" striped exportable={{ formats: ["pdf"], pdf: { libraries, matchGridStyle: true } }} />
+```
+
+Fonts are not copied: jsPDF cannot use a web font without its file (see `fontName`).
+
+**2. Set it yourself with `style`.** Every field is optional, and colours are any CSS colour (`"#4f46e5"`, `"rgb(79,70,229)"`, `"tomato"`).
+
+```tsx
+pdf: {
+  libraries,
+  margin: { top: 60, right: 30, bottom: 50, left: 30 },
+  tableTheme: "grid",                                  // "striped" | "grid" | "plain"
+  style: {
+    pageBackground: "#0f172a",                         // colour behind everything, on every page
+    headColor: "#f59e0b",
+    headTextColor: "#111827",
+    stripeColors: ["#1e293b", "#334155"],              // rows alternate between these two
+    bodyTextColor: "#e2e8f0",
+    borderColor: "#475569",
+    borderWidth: 0.4,                                  // points
+    cellPadding: { top: 6, bottom: 6, left: 8, right: 8 },
+    fontSize: 10,
+    columns: {                                         // per column, by its `field`
+      salary: { fontStyle: "bold", textColor: "#fbbf24", align: "right" },
+      name: { width: 120 },
+    },
+  },
+}
+```
+
+| `style` field | Meaning |
+| --- | --- |
+| `headColor`, `headTextColor`, `headFontSize`, `headFontStyle` | The table's header row (`headFontStyle`: `"normal"`, `"bold"` (default), `"italic"`, `"bolditalic"`) |
+| `bodyColor` | Background of every body row (when there are no `stripeColors`) |
+| `stripeColors` | `[colorA, colorB]`: rows alternate, starting with A |
+| `bodyTextColor` | Text colour of body rows |
+| `borderColor`, `borderWidth` | Lines between cells (points) |
+| `cellPadding` | Space inside cells: a number or `{ top, right, bottom, left }`. Default 4 |
+| `minRowHeight` | Smallest row height in points |
+| `fontSize`, `fontName` | Table text size (default 9) and a font you registered |
+| `pageBackground` | Paper colour. Header, footer, title and table text turn light by themselves when it is dark |
+| `textColor`, `titleColor`, `titleSize` | Header / footer / page-number text, and the `title` |
+| `margin` | Same as the `margin` option |
+| `columns` | `{ [field]: { width, align, textColor, backgroundColor, fontStyle, fontSize } }`. `width` is points, `"auto"` or `"wrap"` |
+
+**Which wins.** Weakest to strongest: built-in defaults, the grid's look (`matchGridStyle`), the flat options (`headColor`, `fontSize`, `margin`, ...), then `style`. So you can copy the grid and still force one colour:
+
+```tsx
+pdf: { matchGridStyle: true, style: { headColor: "#0f766e" } }     // the grid's look, but a teal header
+```
+
+**Anything else.** `autoTableOptions` is handed to jspdf-autotable last, and its `styles`, `headStyles`, `bodyStyles`, `alternateRowStyles` and `margin` are merged key by key into ours:
+
+```tsx
+pdf: { autoTableOptions: { rowPageBreak: "avoid", didParseCell: (data) => { if (data.column.index === 5 && Number(data.cell.raw.replace(/\D/g, "")) > 100000) data.cell.styles.textColor = [220, 38, 38]; } } }
+```
+
+Header and footer *elements* are drawn on the page's colour, so they blend into a `pageBackground`.
+
+#### 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`:
 
@@ -2131,7 +2529,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:
 
@@ -2154,6 +2677,10 @@ 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.
+- The PDF is styled by its own `pdf` options. It only copies the grid's look when `matchGridStyle` is on, and then only colours, stripes, borders and text size, not fonts or exact spacing.
+- 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.
 
 ---
 
@@ -2176,6 +2703,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:
 
@@ -2189,7 +2717,8 @@ Open the URL it prints (usually `http://localhost:5173`). Link straight to a dem
 The Styling demo loads Tailwind from its CDN, so it needs an internet connection. The rest works offline.
 
 ---
-## 8. Troubleshooting
+
+## 9. Troubleshooting
 
 | Problem | Cause and fix |
 | --- | --- |
@@ -2203,6 +2732,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 jspdf and jspdf-autotable libraries` | Install `jspdf jspdf-autotable` (and `html2canvas` for a header / footer element) and pass them in `exportable.pdf.libraries`. 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 |
@@ -2231,28 +2766,6 @@ The Styling demo loads Tailwind from its CDN, so it needs an internet connection
 | 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` |
 
 ---
-
-## 9. Migrating from the earlier version
-
-### Renamed: react-gridix
-
-The library is now **`react-gridix`**, and every CSS prefix changed from `rk` to `rg`.
-
-| Before | Now |
-| --- | --- |
-| `npm install react-ui-kit` | `npm install react-gridix` |
-| `import ... from "react-ui-kit"` | `import ... from "react-gridix"` |
-| `import "react-ui-kit/style.css"` | `import "react-gridix/style.css"` |
-| CSS variables `--rk-header-bg`, `--rk-primary`, ... | `--rg-header-bg`, `--rg-primary`, ... |
-| Classes `.rk-grid__row`, `.rk-checkbox`, ... | `.rg-grid__row`, `.rg-checkbox`, ... |
-| Theme selector `[data-rk-theme="brand"]` | `[data-rg-theme="brand"]` |
-
-Search your project's CSS for `rk-` and replace it with `rg-`. A one-line fix in a Unix shell: `sed -i 's/\brk-/rg-/g' src/**/*.css`.
-
-### Other changes
-
-Also new in this release: `filterDebounce`, a smaller default checkbox (17px instead of 20px, with a tighter gap and a narrower selection column), a calendar for date cells and date filters, the `sequence` column type, `rowAnimationClassName`, and re-tuned theme colours (stronger header contrast, clearer inputs in the dark themes).
-
 ### Changed defaults
 
 Three defaults changed so that every feature is opt-in.