gridcn2.0.0
Data modes

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. data holds every row in memory.
  • PC: Client pagination. defaultPageSize pages the view of the whole data.
  • PS: Server pagination. The server returns one page per request.
  • Z: Scroll mode. useDataGridServerRows in scroll mode fetches row blocks on scroll.
  • C: Controlled state. The app owns sortState, filterState or searchText.
  • SS: Server sort. sortMode="server": the grid never reorders data.
  • FS: Server filter. filterMode="server": the grid never filters data.
  • API: Own API. onSave (or your onDataChange) writes each change to the app's backend.

Matrix

  • Supported
  • Not applicable
FeatureLPCPSZCSSFSAPI
SortSupportedSupportedSupportedSupportedSupportedSupportedNot applicableSupported
FilterSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Filter set valuesSupportedSupportedSupportedSupportedSupportedSupportedSupportedNot applicable
Row check and rangesSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Row idsSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Row countSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Row groupingSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Pinned rows and aggregatesSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Server totals (useDataGridServerAggregate)Not applicableNot applicableSupportedSupportedSupportedSupportedSupportedSupported
Column pin, hide, order and sizeSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Clipboard copy and pasteSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
FillSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
ImportSupportedNot applicableSupportedSupportedNot applicableNot applicableNot applicableSupported
ExportSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Import check before the saveSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
PrintSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Undo and redoSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Row create, duplicate, delete, and moveSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
ValidationSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Edit commit and write-throughSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Streaming updatesSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Pushes into a server-ordered viewNot applicableNot applicableSupportedSupportedSupportedSupportedSupportedSupported
URL stateSupportedSupportedSupportedSupportedNot applicableSupportedSupportedSupported
Saved viewsSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Screen reader announcementsSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Header tab stops with zero rowsSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
PresenceSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Cell commentsSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Loading and error stateSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Find and replaceSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Export output and cell shapingSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Import cell hookSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Replace plan cut by a hookSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Scroll row fetchingNot applicableNot applicableNot applicableSupportedSupportedNot applicableNot applicableNot applicable
Scroll fetch limitsNot applicableNot applicableNot applicableSupportedSupportedSupportedSupportedSupported
Revalidation on a timerNot applicableNot applicableSupportedSupportedSupportedSupportedSupportedSupported
Next page prefetchNot applicableNot applicableSupportedNot applicableSupportedSupportedSupportedSupported
PaginationNot applicableSupportedSupportedNot applicableSupportedSupportedSupportedSupported
Keys, labels and cell typesSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Column groupsSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Context menuSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Status barSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Sort listSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Keybindings dialogSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Touch gesturesSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Row reorderSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Right-to-left layoutSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Unknown total and cursor pagingNot applicableNot applicableSupportedSupportedSupportedSupportedSupportedSupported
One server data source (useDataGridServerRows)Not applicableNot applicableSupportedSupportedSupportedSupportedSupportedSupported
First server answer without a request (initialAnswer)Not applicableNot applicableSupportedSupportedSupportedSupportedSupportedNot applicable
Error state and retryNot applicableNot applicableSupportedSupportedSupportedSupportedSupportedSupported
Debounced text inputsSupportedSupportedSupportedSupportedSupportedSupportedSupportedNot applicable
Async lookup cellSupportedSupportedSupportedSupportedSupportedSupportedSupportedSupported
Server query layer (ORM adapters)Not applicableNot applicableSupportedSupportedSupportedSupportedSupportedNot applicable

Notes

Sort

  • locale also sets the sort language when sortLocale is 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.

  • The grid's search highlights and navigates loaded rows and never narrows them. useDataGridServerRows sends the text as spec.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.
  • useDataGridServerRows puts the search text in spec.searchText, bounds it in parseServerSpec, 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 useDataGridAggregate totals it without a fetch.
  • PC: n/a: A client grid with defaultPageSize holds every row, so useDataGridAggregate totals 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

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 maxLoadedRows evicts on a sequential source too. The hook stores the request that loaded each block (its start, end and the cursor the server returned for it). The hook sends that request again when the user scrolls back. fetchRows must 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

  • prefetchNextPage has no effect while groupBy is set. The hook warns once in development. revalidateIntervalMs and reshapeDelayMs still apply to grouped sources.
  • L, PC: n/a: Rows are in memory.
  • Z: n/a: overscan already 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 a nextCursor chain: each page request carries the cursor of 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 data is the total.

One server data source (useDataGridServerRows)

  • L: n/a: A local array needs no fetch.
  • PC: n/a: A client grid with defaultPageSize holds 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 defaultPageSize holds 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.

On this page