Grid props

<ActiveGrid> component, GridProps<TData> discriminated union, all base props, imperative handle, settings, pagination, toolbar, header/row menus, and footer.

ActiveGrid Component#

import {ActiveGrid} from '@workspace/active-grid';

The main grid component. Accepts GridProps<TData> which is a discriminated union based on the mode prop.

GridProps (Client Mode)#

<ActiveGrid  mode="client"  data={TData[]}  // ... all common base-props (see section below)/>

GridProps (Server Mode)#

<ActiveGrid  mode="server"  fetchFn={ServerFetchFunction<TData>}  // ... all common base-props (see section below)/>

Common base props#

All props shared between client and server mode. These are the intersection of GridProps-client and GridProps-server. There is no standalone type-export for this intersection; use GridProps<TData> and discriminate on the mode-field.

Loading display#

Why the default is nothing#

A grid has three states, and they are not interchangeable: it has not loaded yet, it has loaded and found nothing, or it has loaded and has rows. Two of those look identical if you only count rows, which is how a grid ends up saying "No results" while it is still fetching.

Two things follow, and they are of different kinds.

Whether an indicator is shown is your decision, not the library's. Only you know whether your data arrives in 50 ms or in 3 seconds. An indicator that appears and disappears within 80 ms is more disturbing than an empty area, and a library that guesses will be wrong for half its consumers. So the default for a first load is 'none'.

Whether the grid states something untrue is not your decision. Regardless of loadingDisplay, the pagination footer stays silent — no row count, no page indicator — until a fetch has answered. That is correctness and it is not configurable. With 'none' as the default it matters more, not less: it is the only thing between an empty area and a false statement.

A refetch is the one place the library still leans in. Rows are on screen and they have just gone stale; a reader given no cue is looking at old data without knowing it. The default there is the 2-pixel bar. Set refetch: 'none' if you disagree.

Type#

type LoadingIndicator = 'none' | 'progress' | 'skeleton' | 'spinner' | 'text';
// An indicator name, or your own node rendered inside the grid box.type LoadingDisplayValue = LoadingIndicator | React.ReactNode;
interface LoadingDisplayOptions {  firstLoad?: LoadingDisplayValue; // default 'none'  refetch?: LoadingDisplayValue; // default 'progress'  delayMs?: number; // default 0}
loadingDisplay?: LoadingIndicator | LoadingDisplayOptions;

All three are exported, so a wrapper can name them:

import type {  LoadingDisplayOptions,  LoadingDisplayValue,  LoadingIndicator,} from '@workspace/active-grid';
// A per-screen choice passed down to a shared grid wrapper.function AppGrid({busyState}: {busyState: LoadingDisplayValue}) { … }

Indicators#

Two details worth knowing. 'skeleton' renders nothing when the column widths are not resolved yet — it does not silently become a spinner. And the bar and the skeleton stop animating under prefers-reduced-motion; they stay visible, they just hold still.

Why 'skeleton' stays#

'skeleton' is an explicit library capability. Host applications decide which loading presentations their own design standards permit; supporting a value does not require a host to use it. The repository's PAGE_STANDARDS.md section 7 restricts product loading UI while allowing this library capability.

Nothing about the default behaviour depends on this. firstLoad defaults to 'none' and refetch to 'progress', so a consumer that says nothing never sees a skeleton — it has to be asked for by name.

Every way to write it#

// Default: nothing on first load, the bar on a refetch.<ActiveGrid mode="server" fetchFn={fetchFn} columns={columns} gridId="a" />
// Short form — symmetric. This is skeleton in BOTH states.<ActiveGrid loadingDisplay="skeleton" ... />
// Per state.<ActiveGrid loadingDisplay={{firstLoad: 'skeleton', refetch: 'progress'}} ... />
// Only override one; the other keeps its default.<ActiveGrid loadingDisplay={{firstLoad: 'text'}} ... />
// Hold anything back until the fetch has run 300 ms. A faster fetch// shows nothing at all — this is what removes the flash.<ActiveGrid loadingDisplay={{firstLoad: 'skeleton', delayMs: 300}} ... />
// Your own node — any ReactNode. The grid box is the positioning context.<ActiveGrid loadingDisplay={{firstLoad: <div>Loading orders…</div>, refetch: 'none'}} ... />
// Silence everywhere.<ActiveGrid loadingDisplay="none" ... />

delayMs is recommended alongside every visible indicator; 200-300 ms is a common choice. It is not defaulted to a non-zero value on purpose — that would be the library deciding again.

Filter axis: client mode only#

externalFilter and enableFilterBuilder are declared on the shared base-props, so the type-checker accepts them in both modes — but both are applied in exactly one place, and that place is client-only. use-grid-setup.ts filters the client dataset under mode === 'client'; the filter-builder's AND/OR expression is evaluated into that same predicate. Nothing is serialised onto the wire: ServerFetchParams carries filters, sorting and globalFilter, and has no expression field.

The two get different treatment in server mode, because they fail differently:

Both warnings are development-only (silent in production) and fire only when the prop is actually set — an ordinary server-mode grid is never warned about.

Consequence worth stating explicitly. When externalFilter is used to hide rows (a view-tab predicate, a scope restriction), a server-mode grid shows the user more than the consumer intended. That is a visibility gap, not a data leak: permission and tenant scoping are enforced server-side by the resource layer and never depend on this predicate. Still, move the condition into the server query (fetchFn params, or a resource filter) rather than relying on the predicate.

Roadmap item F-12 covers wiring the expression tree into the server query. This is "not yet", not "never".

Initial page size#

initialPageSize is the page size a grid opens at when it has no pagination state of its own. It is a starting value, not an override: it never replaces what a user chose or shared.

The initial… prefix is deliberate. A grid starting value is one link in a precedence chain with URL and stored state (GridStatePriority), so it is not the plain React initial value of uncontrolled state that a default… prop names elsewhere in the package family (ADR-045 § 8). Callback names (on…) are the same in both packages.

Precedence#

From strongest to weakest:

Sources 1 and 2 are ordered against each other by statePriority (default 'url-first') — see Precedence against localStorage. That arbitration is unchanged; the prop and the boundary sit strictly below both.

Steps 3, 4 and 5 are the same shape every other GridConfig setting has: a per-grid prop wins over the nearest GridDefaults, and that boundary wins over the package default. See columns.md § GridDefaults.

Consequences worth stating:

• pageIndex always starts at 0. The prop names a size, never a page.

• The first render already carries the size. The value seeds the store rather than arriving from an effect, so there is no visible jump from 10 to the configured size. Server and client agree on it — it comes from a prop, not from localStorage or the URL — so it is also hydration-safe.

• A later render with a different value does not reset a running grid. The starting state is decided once, at mount.

• A stale persisted or URL value still wins. A user who once chose 100 keeps 100, even when the code later declares initialPageSize={20}. Clearing the stored state (clearAllGridStates()) brings the grid back to initialPageSize, not to 10.

• Two grids are independent. Each gridId has its own store and its own starting size. Two grids under the same provider share the baseline unless one of them sets initialPageSize.

• A provider re-render does not reset a running grid. The starting state is decided once, at mount, from both sources. To see a new configured value, remount the grid.

Invalid values#

A value that is present but not a whole number greater than zero (0, a negative, a fraction, NaN) is refused, not repaired. It is not clamped to 1 and not rounded — either would turn a typo into a working grid that silently disagrees with its source. A console.warn in development names the grid and the source that was rejected.

A refused value counts as absent, so the chain simply continues: an invalid initialPageSize falls through to GridConfig.pagination.pageSize, and an invalid provider value falls through to the package default. The other reading — a typo in one grid discards the deliberately configured platform value — would punish the installation for a mistake somewhere else.

The value is deliberately not checked against pageSizeOptions. That list validates the URL, which is user input and an abuse surface (pageSize=10000); initialPageSize comes from the developer composing the grid, and the paginator already appends a size outside the list to its selector.

Fixed in 10.1.3. Before that release the prop only reached the state through the pagination branch of state hydration, which runs only when the URL or localStorage already carries a pagination slice. On a fresh grid — exactly what "initial" names — it did nothing.

Extended in 10.2.0. GridConfig.pagination.pageSize was declared, defaulted and documented — with a provider example that invited consumers to set it — and read by nothing. It is now step 4 of the chain above. A consumer who already set it and saw no effect will now get the value they asked for.

State persistence#

With enablePersistence, grid state is written to localStorage under active_grid_state_<gridId>. Two further namespaces exist for auxiliary state: active_grid_state_locks_<gridId> (locked columns) and active_grid_state_pins_<gridId> (pinned rows).

What is validated on load#

A stored entry is only trusted after two checks:

1. Version. A version that does not match the configured storage version is discarded and the key is removed.

2. Shape, per slice. Every slice is checked against the structure it is supposed to have — sorting an array of {id: string, desc: boolean}, columnSizing a record of finite numbers, pagination an object with a non-negative pageIndex and a positive pageSize, and so on. The same applies to the two auxiliary namespaces.

A version check alone is not enough: state can be corrupt within a valid version, for instance after a hand-edit of localStorage or a restore from another source.

What happens to an invalid slice#

The slice is ignored and falls back to its default. It is never repaired or converted — there is no migration mechanism.

Validation is per slice, not all-or-nothing: the remaining slices are restored normally. A single corrupt columnOrder therefore does not cost you your column widths or your saved filters. This is a robustness boundary for UI preferences, not a security boundary, so discarding state the user could have kept is the worse outcome.

A completely unreadable entry (not JSON, or JSON that is not an object) yields no state at all and never throws.

The warning#

Each ignored slice logs a console.warn naming the slice, the grid ID and the kind of value that was rejected:

[active-grid] ignored persisted "pagination" for grid "audit-log" — the storedvalue does not match the expected shape (received an array of 2). The slicefalls back to its default; the other slices were restored.

This warning appears in development only (process.env.NODE_ENV !== 'production'). The slice is dropped in production too — only the message is suppressed. State that disappears without a signal is the hardest kind to explain, which is why the drop is announced at all.

What is written#

A save writes exactly the slices a load restores: sorting, columnFilters, columnVisibility, columnOrder, columnSizing, columnPinning, pagination, globalFilter, rowPinning and expanded, plus the storage version and a timestamp. Runtime state is never written: row selection, grouping, the live resize bookkeeping and cell selection belong to one visit. An older entry that still carries such fields loads without complaint; they are not restored, and the next save leaves them out.

A column width the reader set by dragging is a lock in active_grid_state_locks_<gridId>. The locks are read before the grid's first layout pass, and no layout pass runs before they are known, so a restored width survives the reload and every later resize of the viewport.

URL state#

With enableUrlSync, the grid mirrors part of its state into the query string so a view can be shared, bookmarked and reloaded.

What the grid owns#

Exactly five keys, and this list is exhaustive:

page and pageSize are read strictly: only decimal digits state a number, and both must be a whole number greater than zero. page=2junk, page=1.5, page=-1, page=0 or an empty value states no page, so the grid keeps its starting page instead of a truncated or clamped one; pageSize follows the same rule.

No other grid state reaches the URL. Column sizing, ordering, pinning, visibility, row pinning and client expansion are localStorage-only, under enablePersistence. Server-group expansion is separate, non-persisted hook state (see Server grouping) — they are per-device preferences, not part of a view you share with a colleague.

What the grid does NOT touch#

A grid manages only its own URL state. Every query parameter outside the five keys above belongs to the application, and the grid carries it through untouched: same value, same multiplicity (two ?tag= pairs stay two pairs), same relative order. It is never rewritten, re-encoded or dropped.

This matters for composition. A route can carry a tab id under ?section=, a server-evaluated view under ?view=, or any other app-owned deep-link dimension, and put a URL-synced grid on the same page:

/records?view=recent&page=2&sort=createdAt:desc

Sorting, paging, filtering, searching and clearing the grid state all leave view=recent exactly where it is.

Fixed in the release after 9.0.0. The write-back used to replace the whole query string, so an app-owned parameter disappeared on the first grid interaction — a deep link that worked once and then quietly did not. Consumers whose routes carry no parameters besides grid state see no behavioural change at all: for them the merge produces the same string the replacement did.

Not promised: byte-exact reproduction of the whole URL. The grid re-serializes its own keys from state, so their order and encoding come from the serializer and they are appended after the application's parameters.

History semantics#

The write-back uses history.replaceState, never pushState: a sort is not a navigation, and back/forward keep meaning what they meant before the grid state changed. This is unchanged behaviour.

Two grids on one route#

The five keys are global to the route, not namespaced per gridId. Two URL-synced grids on the same route therefore compete for them and the last writer wins. Give at most one grid per route enableUrlSync; a second grid on the same route uses enablePersistence only. (The grid does not warn about this — it cannot see its siblings.)

Precedence against localStorage#

When both enableUrlSync and enablePersistence are on, the four contested slices (sorting, filters, global filter, pagination) resolve per statePriority, default 'url-first'. A shared link therefore wins over the recipient's own saved state, which is what makes it a link worth sharing.

GridImperativeHandle#

import {type GridImperativeHandle} from '@workspace/active-grid';

Production consumer-code must use useGridMutation instead of calling these methods directly. See server-mode.md for the hook and the three exception classes (library tests, demo pages, pure UI commands outside a mutation flow).

SelectionModel#

import {type SelectionModel} from '@workspace/active-grid';

Discriminated union for row-selection state:

type SelectionModel =  | {mode: 'inclusive'; rowIds: string[]}  | {      mode: 'exclusive';      excludedRowIds: string[];      totalCount: number;      query: SelectionQuery;    };

Inclusive mode (default) tracks selected rows by ID. Exclusive mode (used for server-side "select all 5000 rows") tracks excluded rows; everything else is considered selected.

totalCount is for display. It is what the last response reported. A mutation must never compute its own effect from it: rows can appear or disappear between the selection and the call, and the number arrives from the client anyway.

SelectionQuery#

import {  type SelectionQuery,  type SelectionQueryFilter,} from '@workspace/active-grid';

The QUESTION an exclusive selection answers. "Everything except these ids" is meaningless without it: a consumer that cannot see the query either processes the rows it happens to have loaded (silently wrong) or the whole table (dangerously wrong).

interface SelectionQueryFilter {  readonly id: string;  readonly value: unknown;}
interface SelectionQuery {  /** Column filters the grid itself owned at selection time. */  readonly filters: ReadonlyArray<SelectionQueryFilter>;  /** The grid's own search term; `''` when the grid has no search. */  readonly search: string;  /** The consumer's `serverQueryKey`, verbatim; `undefined` when unused. */  readonly externalKey: string | undefined;}

Split by OWNER: filters and search are the grid's, externalKey is the consumer's. The grid never parses any of it — it is carried, not interpreted, so a consumer can verify the selection still belongs to the scope on screen. A mutation must still re-derive and re-authorize all of it server-side; see ../guides/selection.md.

GridSelectionAction#

import {  type GridSelectionAction,  type GridSelectionActionTone,} from '@workspace/active-grid';

One action offered on the current selection. The grid owns the bar, the count, the fixed Actions menu, the keyboard behaviour and the two presentations; the consumer owns which actions exist, what they are called and what they do.

Permission is absence. An action the caller may not perform is left out of the array; the grid never renders a disabled item to stand for a missing right.

There is no ReactNode slot. A free slot would let every consumer design its own bulk bar again, which is the divergence this contract replaces. One action renders in the same menu as five.

supportsDatasetWideSelection closes the affordance gap. A grid that offers "select all 5000 rows" next to an action that can only process explicit ids invites the reader into a state where the action either does nothing or silently does less than it says. The declaration works in both directions:

• an action that cannot execute the exclusive shape is left OUT of the menu while such a selection is active;

• when NO declared action can execute it, the grid does not offer dataset-wide select-all in the first place.

Set it to false when the action needs explicit ids — because its server side takes an id list, or because the work is unbounded and has no background carrier. Leave it true when the server can re-derive the query, re-authorize it and apply the exclusions itself.

GridSettings#

import {type GridSettings} from '@workspace/active-grid';

Visual settings via the settings prop:

GridHeaderConfig#

GridFooterConfig#

GridPaginationOptions#

GridToolbarConfig#

import {type GridToolbarConfig} from '@workspace/active-grid';

Configuration for the toolbar above the grid. Opt-in: only renders when at least one feature is enabled (search.enabled, showColumnChooser, or actions).

Search input (inline shape)#

GridHeaderMenuConfig#

import {type GridHeaderMenuConfig} from '@workspace/active-grid';

Per-column header-menu (3-dot button) configuration. Set globally via the headerMenu prop or per-column via meta.headerMenu.

Header-menu features (inline shape)#

GridRowMenuConfig#

import {type GridRowMenuConfig} from '@workspace/active-grid';

Row context-menu (right-click) configuration via the rowMenu prop.

Row-menu features (inline shape)#