Data mode support
Look up which grid features work in each data mode, and where a known gap remains.
A grid feature can behave differently on a local array, on server pages and on scrolled server rows. The table below sets every feature against every data mode. A gap cell is a known gap, and the notes below the table describe it.
Data modes
- L: Local array.
dataholds every row in memory. - PC: Client pagination.
defaultPageSizepages the view of the wholedata. - PS: Server pagination. The server returns one page per request.
- Z: Scroll mode.
useDataGridServerRowsin scroll mode fetches row blocks on scroll. - C: Controlled state. The app owns
sortState,filterStateorsearchText. - SS: Server sort.
sortMode="server": the grid never reordersdata. - FS: Server filter.
filterMode="server": the grid never filtersdata. - API: Own API.
onSave(or youronDataChange) writes each change to the app's backend.
Matrix
- Supported
- Not applicable
| Feature | L | PC | PS | Z | C | SS | FS | API |
|---|---|---|---|---|---|---|---|---|
| Sort | Supported | Supported | Supported | Supported | Supported | Supported | Not applicable | Supported |
| Filter | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Filter set values | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Not applicable |
| Quick search | Supported | Supported | Supported | Supported | Supported | Supported | Not applicable | Not applicable |
| Server search | Not applicable | Not applicable | Supported | Supported | Supported | Supported | Supported | Not applicable |
| Row check and ranges | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Row ids | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Row count | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Row grouping | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Pinned rows and aggregates | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
Server totals (useDataGridServerAggregate) | Not applicable | Not applicable | Supported | Supported | Supported | Supported | Supported | Supported |
| Column pin, hide, order and size | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Clipboard copy and paste | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Fill | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Import | Supported | Not applicable | Supported | Supported | Not applicable | Not applicable | Not applicable | Supported |
| Export | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Import check before the save | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported | |
| Undo and redo | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Row create, duplicate, delete, and move | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Validation | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Edit commit and write-through | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Streaming updates | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Pushes into a server-ordered view | Not applicable | Not applicable | Supported | Supported | Supported | Supported | Supported | Supported |
| URL state | Supported | Supported | Supported | Supported | Not applicable | Supported | Supported | Supported |
| Saved views | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Screen reader announcements | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Header tab stops with zero rows | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Presence | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Cell comments | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Loading and error state | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Find and replace | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Export output and cell shaping | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Import cell hook | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Replace plan cut by a hook | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Scroll row fetching | Not applicable | Not applicable | Not applicable | Supported | Supported | Not applicable | Not applicable | Not applicable |
| Scroll fetch limits | Not applicable | Not applicable | Not applicable | Supported | Supported | Supported | Supported | Supported |
| Revalidation on a timer | Not applicable | Not applicable | Supported | Supported | Supported | Supported | Supported | Supported |
| Next page prefetch | Not applicable | Not applicable | Supported | Not applicable | Supported | Supported | Supported | Supported |
| Pagination | Not applicable | Supported | Supported | Not applicable | Supported | Supported | Supported | Supported |
| Keys, labels and cell types | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Column groups | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Context menu | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Status bar | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Sort list | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Keybindings dialog | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Touch gestures | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Row reorder | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Right-to-left layout | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Unknown total and cursor paging | Not applicable | Not applicable | Supported | Supported | Supported | Supported | Supported | Supported |
One server data source (useDataGridServerRows) | Not applicable | Not applicable | Supported | Supported | Supported | Supported | Supported | Supported |
First server answer without a request (initialAnswer) | Not applicable | Not applicable | Supported | Supported | Supported | Supported | Supported | Not applicable |
| Error state and retry | Not applicable | Not applicable | Supported | Supported | Supported | Supported | Supported | Supported |
| Debounced text inputs | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Not applicable |
| Async lookup cell | Supported | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| Server query layer (ORM adapters) | Not applicable | Not applicable | Supported | Supported | Supported | Supported | Supported | Not applicable |
Notes
Sort
localealso sets the sort language whensortLocaleis not set.- FS: n/a: Filter mode concerns filters only.
Filter
A sort or filter on a column that is not in columns drops with a development warning, in every mode. filterJoin joins the top-level filters with and (default) or or. A server request carries filterJoin: "or" in the spec. FilterGroup.not: true negates a group in every mode. The server spec carries it on the group.
Filter set values
API: n/a: Set values are read-only input of the filter. Writes through onDataChange or onSave never read them.
Quick search
- The grid's search highlights and navigates loaded rows and never narrows them.
useDataGridServerRowssends the text asspec.searchText, so your server can narrow the result. - FS: n/a: Search highlights loaded rows and never filters.
- API: n/a: Search writes no data.
Server search
useDataGridServerRowsputs the search text inspec.searchText, bounds it inparseServerSpec, and refetches. Your server narrows the result by it.- L: n/a: A local array has no server to send the text to.
- PC: n/a: Client pagination searches the whole local
data. - API: n/a: Search writes no data.
Row count
A development warning names totalRowCount above the loaded rows under a client sort or filter. It never fires when sortMode and filterMode are both server.
Server totals (useDataGridServerAggregate)
- L: n/a: A local array holds every row, so
useDataGridAggregatetotals it without a fetch. - PC: n/a: A client grid with
defaultPageSizeholds every row, souseDataGridAggregatetotals it without a fetch.
Column pin, hide, order and size
Mode-neutral. Autosize measures loaded rows only on scroll data and on one page.
Fill
Fill skips rows not loaded yet and warns.
Import
PC, C, SS, FS: n/a: Import hands the built rows to onImport and reads no sort, filter, page, or server state. The app decides where they land.
Import check before the save
checkImport reads the built rows and takes an answer from any promise. The dialog writes nothing. On the server, parseImportRows reads the import request with bounds and answers the refusals.
Print covers the rows the grid holds: every page of a client-paged grid, the loaded page or blocks of a server grid.
Row create, duplicate, delete, and move
The move operation carries beforeRowId and afterRowId, so a server receives the neighbors in change.ops.
Validation
Delete and Cut run the column validate on the empty value in every mode. A server grid still checks the save in onSave.
Edit commit and write-through
editRows writes with source edit, so a server grid receives it in onSave.
Streaming updates
reorder: "frame" re-places the patched rows once per animation frame on a client view. Where a server owns the order, it follows the "defer" rule (tests/parity/push-reshape.parity.test.tsx).
Pushes into a server-ordered view
L, PC: n/a: The client sorts and filters the pushed rows itself. With the default reorder: "defer", a pushed row keeps its position and viewStale turns on. reconcileView() or the next sort, filter, or search change moves the row. reorder: "immediate" moves it at once. See Stream updates.
URL state
C: n/a: URL state drives the controlled props itself.
Presence
Mode-neutral by design.
Cell comments
Mode-neutral by design. Comments are addressed by row id and column id, so a sort, a filter, a page change, or an eviction moves markers and never comments. fetchComments loads the comments of the rendered rows. Without currentUser and onCommentSave, comments are anonymous and stay on the client. onCommentSave covers your own API, and applyRemote takes the changes of other clients.
Scroll row fetching
- L, PC: n/a: Rows are in memory.
- PS: n/a: Pages mode requests one page per state. See Load rows by page.
- SS: n/a: Not a sort concern.
- FS: n/a: Not a filter concern.
- API: n/a: Not a write concern.
Scroll fetch limits
- A finite
maxLoadedRowsevicts on a sequential source too. The hook stores the request that loaded each block (itsstart,endand thecursorthe server returned for it). The hook sends that request again when the user scrolls back.fetchRowsmust answer a repeated cursor with the same rows. A block with an open edit, a pending save, or an unsaved change stays loaded. The chain goes on with the cursor of its last block. - L, PC: n/a: Rows are in memory.
- PS: n/a: A pages-mode request is one per state. A newer page aborts the older one.
Revalidation on a timer
L, PC: n/a: Rows are in memory.
Next page prefetch
prefetchNextPagehas no effect whilegroupByis set. The hook warns once in development.revalidateIntervalMsandreshapeDelayMsstill apply to grouped sources.- L, PC: n/a: Rows are in memory.
- Z: n/a:
overscanalready loads rows ahead on both sides.
Pagination
- L: n/a: No pages.
- Z: n/a: Scroll mode and pagination are exclusive.
Keys, labels and cell types
Mode-neutral.
Column groups
Mode-neutral.
Context menu
Mode-neutral.
Status bar
Mode-neutral.
Sort list
Mode-neutral.
Keybindings dialog
Mode-neutral.
Touch gestures
Mode-neutral.
Row reorder
Mode-neutral.
Right-to-left layout
Mode-neutral.
Unknown total and cursor paging
- Pages mode pages without a total through
hasMore, or through anextCursorchain: each page request carries thecursorof the page before. Scroll mode loads a source without a count in order. - L: n/a: The array holds every row.
- PC: n/a: The length of
datais the total.
One server data source (useDataGridServerRows)
- L: n/a: A local array needs no fetch.
- PC: n/a: A client grid with
defaultPageSizeholds every row, so no fetch runs.
First server answer without a request (initialAnswer)
- L: n/a: A local array needs no fetch.
- PC: n/a: A client grid with
defaultPageSizeholds every row, so no fetch runs. - API: n/a: The first answer is an option of the server hook, not an action.
Error state and retry
L, PC: n/a: No request can fail.
Debounced text inputs
API: n/a: The inputs write no data.
Async lookup cell
Mode-neutral: the editor fetches options, not rows. A text filter operator sends the label text and the server compares labels. IsAnyOf and isNoneOf send the entries of the set list, which fetchFilterValues fills with keys.
Server query layer (ORM adapters)
- L: n/a: The layer runs on the consumer's server. A local array has no server.
- PC: n/a: Client pagination pages data the grid already holds.
- API: n/a: The layer reads rows. Writing rows stays the consumer's code.
Related
- Server rows contract: the request and the answer
- Load rows while scrolling: load rows as the user scrolls
- Load rows by page: load rows by page