Documentation
Concepts

Rows in memory

Sort, filter, search and page the rows you hold in the browser with one hook, or send the same state to your server.

The grid shows the rows it is given, in that order. The sort, the column filters, the search text and the page are the grid's state, each kept by a feature: sorting(), filtering(), search() and pagination(). When every row is in memory, one hook does the rest: it applies the state of the features you install to your rows and hands the grid the rows to show. A grid fed by a server never loads it: it sends the same state.

Rows in memory
Gallery

One hook

useLocalRows(rows, columns, options) comes from its own entry point, @fragiola/data-grid-react/local. Give it the root's features (features): each of sorting(), filtering(), search() and pagination() installed runs its stage, one left out is skipped (its controls change nothing). Spread its props onto DataGrid.Root: the current page's rows, and the state of those features, so a click on a sortable header sorts them. The root's model holds that state, controlled by the hook: model.get("column-filters") reads it, and a command run on the model (model.run("page.set", { pageIndex: 2 })) comes back to the hook. Give its filter and page to your own controls.

people.tsx
import { filtering } from "@fragiola/data-grid-react/filtering";
import { useLocalRows } from "@fragiola/data-grid-react/local";
import { pagination } from "@fragiola/data-grid-react/pagination";
import { search } from "@fragiola/data-grid-react/search";
import { sorting } from "@fragiola/data-grid-react/sorting";

const features = [sorting(), filtering(), search(), pagination()];

const local = useLocalRows(people, columns, {
    features,
    pageSize: 50,
    defaultSortColumns: [{ columnKey: "name", direction: "ascending" }],
});

<input
    value={local.filter.search}
    onChange={(event) => local.filter.setSearch(event.target.value)}
/>
<DataGrid.Root features={features} columns={columns} {...local.props}>
    {/* … */}
</DataGrid.Root>
<button type="button" disabled={!local.page.canNext} onClick={local.page.next}>
    {local.page.index + 1} / {local.page.count}
</button>

It returns:

fieldholds
propsrows, and the state of each feature given, for DataGrid.Root: sortColumns (sorting()), columnFilters (filtering()), searchText (search()), pageIndex, pageSize and totalRowCount (pagination()), each with its handler
rowsthe current page's rows
total, filteredCountevery row given, and those passing the filters and the search
sortcolumns, set, clear
filtervalues, set(columnKey, value), clear, search, setSearch
pageindex, size, count, canPrevious, canNext, set, previous, next, first, last, setSize

The options are where it starts: pageSize (none: a single page of every row), defaultSortColumns, defaultFilters, defaultSearch, defaultPageIndex. A filter, the search or the sort changing goes back to the first page. features is read once, as the root reads its own. The hook controls the state it hands the root: with pagination() installed, the page size is its pageSize option (page.setSize), never the root's defaultPageSize.

Keep rows and columns the same arrays between renders (outside the component, or memoised), as DataGrid.Root wants its columns: the hook works again when they change.

In stages

The rows are filtered, then searched, then sorted, then grouped (with groupBy, Row grouping) or shown as a tree (with getSubRows, Tree data), then paged. Grouped, props carry the expanded groups too (expandedGroupKeys, onExpandedGroupKeysChange) when features has rowGrouping(). A stage whose feature is not in features is skipped. Each stage is worked out again only when its own inputs change: turning a page sorts nothing again, a new sort filters nothing again, and expanding a group groups nothing again.

Sorting

Without anything more, a column's values compare by type: numbers by value, dates by time, false before true, text in the reader's order ("item 2" before "item 10", case and accents aside). Empty values (undefined, null, NaN, "", an invalid date) go last, in either direction. Ties go to the next sorted column, then keep their order.

When a column's values are not its order, give it compare:

columns.tsx
{
    key: "employees",
    name: "Employees",
    width: 150,
    sortable: true,
    // ranges sort by their scale, not as text
    compare: (a, b) => SCALE.indexOf(a.employees) - SCALE.indexOf(b.employees),
}

filter.set(columnKey, value) filters a column by a value. What it matches depends on the value:

filter valuea row passes when its cell
a textcontains it, case and accents aside
a listis one of its values (or holds one, for a cell holding a list): facets
a number, a boolean, a dateequals it
empty (undefined, null, "", [])always: no filter

Filters on several columns all apply. When a column needs another rule, a range for example, give it filter: it receives the cell's value, the filter value and the row.

columns.tsx
{
    key: "salary",
    name: "Salary",
    width: 130,
    // a minimum, not an equal value
    filter: (value, minimum) =>
        typeof value === "number" && typeof minimum === "number" && value >= minimum,
}

filter.setSearch(text) keeps the rows where any column's value, as text, contains it.

Moving rows

The hook never changes the rows you give it. When people move rows, moveRow(move) returns your rows with a move the grid told (onRowMove, with rowReorder()) applied: the moved row goes beside the row it lands next to on screen, a filtered or paged grid's included. Set it as your rows. It is stable (a function that never changes, reading your latest rows), and two moves told before a render apply one after the other. The grid moves no row while it is sorted, nor while the rows are grouped.

backlog.tsx
const [tasks, setTasks] = useState(initialTasks);
const local = useLocalRows(tasks, columns, { features });

<DataGrid.Root
    features={features}
    {...local.props}
    columns={columns}
    onRowMove={(move) => setTasks(local.moveRow(move))}
/>

Without React

The same pipeline is framework-free in @fragiola/data-grid/local: createLocalRows(options) keeps the state (stages, from localStagesOf(features), says which stages run: every one without it) and derive(rows, columns, grouping?) returns the page and the counts (grouped, its groups: the rows shown, their kinds and their keys), and sortRows, filterRows, searchRows and pageRows work on any array, as moveRow(rows, fromIndex, toIndex) and moveShownRow(rows, rowIndexes, fromIndex, toIndex) do for a move (the rows shown by their places among your rows, a view's rowIndexes, so equal rows are told apart).

On a server

With more rows than the browser should hold, install the same features and send their state: the sort (sortColumns, the header toggles it), the column filters (columnFilters), the search text (searchText) and the page (pageIndex, pageSize), controlled by your app or read from the model (model.get("page-info")). Give the root the server's count (totalRowCount), so get("page-count") counts its pages. No /local: the grid shows the page that comes back.

server.tsx
const features = [sorting(), filtering(), search(), pagination()];

<DataGrid.Root
    features={features}
    columns={columns}
    rows={page.rows}
    sortColumns={sortColumns}
    onSortColumnsChange={setSortColumns}
    columnFilters={columnFilters}
    onColumnFiltersChange={setColumnFilters}
    pageIndex={pageIndex}
    onPageIndexChange={setPageIndex}
    pageSize={50}
    totalRowCount={page.total}
/>

The model never moves one piece for another: going back to the first page when a filter changes is your app's (/local does it in memory).

Server-side
Gallery