Server-side data
Everything on this site so far hands the grid an array and it does the work in the browser: a Web Worker sorts and filters, and a million rows stay interactive. That is the right answer for most applications, and it is what the Community edition does.
It stops being the right answer when the data is bigger than a browser tab, or
when it lives behind permissions that must not be evaluated on the client. For
that, implement a DataSource instead of passing an array. Filtering,
sorting, paging, distinct values and footer totals then run on your server,
and the component you render does not change.
Loading from a server is Community (since October 2026): blocks fetched as the user scrolls, sort, filter, search, distinct values, footer totals, Retry and refresh. Enterprise adds what makes the server do more: grouping on the server, a server tree, and an export of the whole result. On a Community grid fed by a server those are not offered — the grouping entries leave the column menu and CSV export leaves the toolbar, because a file of only the rows already loaded would look complete and not be.
The contract
interface DataSource<TRow> {
load(options: LoadOptions): Promise<LoadResult<TRow>>;
byKey?(key: RowKey): Promise<TRow | undefined>;
loadDistinctValues?(options: DistinctValuesOptions): Promise<DistinctValue[] | DistinctValuesPage>;
}
Only load is required. The grid calls it whenever the query changes or it
needs a block of rows it does not hold.
import { DataGrid } from '@kanunilabs/datagrid-react';
const orders = {
async load({ skip = 0, take = 100, sort, filter, searchText, summaries }) {
const res = await fetch('/api/orders', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ skip, take, sort, filter, searchText, summaries }),
});
const data = await res.json();
return {
rows: data.rows,
totalCount: data.total, // the whole filtered result, not this page
summaries: data.totals, // optional; see "Totals" below
};
},
};
<DataGrid
dataSource={orders}
rowKey="id"
columns={columns}
filterRow
/>;
totalCount is the size of the entire filtered result, not of the block you
just returned. It is what sizes the scrollbar, so a wrong number here shows up
as a grid that scrolls into empty space.
What arrives in load
| Field | What it is |
|---|---|
skip / take | The block being asked for. |
sort | Column ids and directions, in priority order. |
filter | A serializable filter AST — the same tree the worker gets. |
searchText | The quick-search box, if the grid has one. |
group / groupKeys | Remote grouping; see below. |
summaries | Footer totals to compute over the whole result. |
The filter is an AST rather than a string on purpose: it survives
JSON.stringify, so the same value can travel to a Web Worker or to your
server, and you translate it into SQL (or whatever you speak) once.
The server side, ready-made: @kanunilabs/datagrid-server
Translating the filter tree into SQL is a few hundred lines that every backend
writes the same way, and it is easy to get the edges different from the grid:
= 0 matching empty cells, a typed % acting as a wildcard, empty values
sorting first on one database and last on another. @kanunilabs/datagrid-server
is that translation, for PostgreSQL, MySQL, SQLite and SQL Server. It has
no dependencies and brings no driver: you pass the function that runs a query.
npm install @kanunilabs/datagrid-server
On the page, the grid's REST source sends the request this package reads:
import { DataGrid, createRestDataSource } from '@kanunilabs/datagrid-react';
const orders = createRestDataSource({ url: '/api/orders', distinctValues: true });
<DataGrid dataSource={orders} rowKey="id" columns={columns} filterRow headerFilter />;
On the server, one loader per table. columns is the whitelist: a request
that names any other column is refused, so a column id never becomes SQL.
// Express + node-postgres
import { createSqlLoader, SqlRequestError } from '@kanunilabs/datagrid-server';
const orders = createSqlLoader({
dialect: 'postgres',
from: 'orders',
key: 'id',
columns: {
id: 'number',
product: 'string',
region: 'string',
units: 'number',
orderedAt: { sql: 'ordered_at', type: 'date' },
},
query: (sql, params) => pool.query(sql, params).then((r) => r.rows),
});
app.get('/api/orders', async (req, res) => {
try {
// Each request can carry its own condition — here, the user's tenant.
res.json(await orders.handle(req.query, { where: (p) => `tenant_id = ${p(req.user.tenantId)}` }));
} catch (e) {
res.status(e instanceof SqlRequestError ? 400 : 500).json({ error: String(e) });
}
});
In a Next.js route handler the query string is already a URLSearchParams:
export async function GET(request: Request) {
return Response.json(await orders.handle(new URL(request.url).searchParams));
}
handle answers the rows, totalCount, the footer totals when the grid asks
for them, a grouping level or a
tree level (with parentColumn set), and
?distinct=region&limit=1000 for the header filter's checklist. Every value is
a bound parameter. The dialect picks the placeholders ($1, ?, @p1),
the paging clause and the identifier quotes.
What it matches. The filters mean what they mean in the grid. Text
compares without case, and contains also folds the Turkish dotted and
dotless i. Both sides of a comparison go through the same SQL, so a value the
header checklist lists always finds its rows, whatever the database's case
rules (a Turkish collation included). An empty cell equals only "empty".
contains takes % and _ literally. Ranges skip empty cells; on SQLite a
date held as text is compared through strftime, so 2026-10-14 10:00:00 and
2026-10-14T10:00:00Z are the same instant (no zone means UTC, as SQLite
reads it). Empty values sort last in both directions, and every page is
ordered by key as well, so no row appears on two pages.
The package's tests run the same filters through the grid's own engine and
through a real SQLite database, and compare the rows. Three things are the
database's to decide:
- Upper/lower case outside ASCII. PostgreSQL, MySQL and SQL Server fold
Öandöalike. SQLite'sLOWERfolds only ASCII unless it is built with ICU. - Sort order of text: your database's collation.
- Quick search looks in
stringcolumns. Setsearchable: trueon another column to include it.
A page larger than maxTake (default 1000) is refused with a 400 rather than
cut short: the grid places a block's rows by position, so a shorter answer
would leave blank rows. Keep remote.blockSize (default 100) and
remote.exportPageSize (default 1000) at or below it, or raise maxTake.
A column's own filter operators
need their SQL from you, by the same id: operators: { startsWithAny: (col, value, p) => … }. An id the server does not know matches no rows, the same
answer the grid gives. With an ORM, buildSqlPlan(options, config) returns
the statements without running them, so you can pass them to Prisma's
$queryRawUnsafe, Drizzle's sql.raw or Knex's raw.
Indexes. Those meanings are expressions over the column — a
case-insensitive = lowers both sides — and a plain index on the column does
not serve an expression: on a million PostgreSQL rows, country = 'France'
took 188 ms instead of 3. indexStatements(config, { columns }) writes the
indexes that do serve them, for your migration. Mark a NOT NULL column
nullable: false ({ type: 'date', nullable: false }) and its sort needs no
NULL handling at all. PostgreSQL sorts with NULLS LAST; MySQL and SQLite get
an index on the same expression the query sorts by; on SQL Server, which
indexes expressions through computed columns, the function throws and says so.
The package is free. Grouping and a tree on the server need the Enterprise grid on the page; the server side is the same package.
Distinct values — the header filter checklist
The header filter popup is a checklist of every distinct value in a column. A client-side grid derives that from the data it holds. A server-side grid cannot: it holds a few blocks, and a checklist built from "whatever happens to be cached" is worse than no checklist — a user would tick four values believing they were all of them.
So the popup is offered only when you implement loadDistinctValues:
async loadDistinctValues({ columnId, limit }) {
const rows = await db
.selectDistinct(columnId)
.orderBy(columnId)
.limit(limit); // apply the limit in SQL, not after
return rows.map((r) => ({ value: r[columnId] }));
}
Without it the popup is simply not offered. The filter row, if you turned it on, still works — it sends a condition, not a list of values.
That is the single list: the first limit values, sorted by the grid, searched
only among themselves. A column with more values than that shows the first ones
only. To list every value, answer the paged request below.
Every value: the paged list
Answer a request that carries skip and take with a page instead of an array:
async loadDistinctValues({ columnId, limit, skip, take, search }) {
if (take === undefined) return legacyList(columnId, limit); // the single list, as above
const values = db.distinct(columnId)
.where(search ? contains(columnId, search) : undefined) // search the WHOLE list
.whereNotNull(columnId) // blanks are not values
.orderBy(columnId) // real order: dates, numbers
.offset(skip).limit(take);
return {
values: values.map((value) => ({ value })), // one slice of the sorted list
totalCount: await db.countDistinct(...), // how many the request matched
hasBlanks: await db.hasNulls(columnId), // the column has blank cells
};
}
The popup then lists every value:
- the scroll bar is
totalCountlong (squeezed under the browser's height limit for a very long list, the way a million rows are), the rows are loaded as they scroll into view, and a jump to the end asks for the last piece, not the pieces on the way; - the text typed in the search box is sent as
search; the server searches, so a value past the first thousand is found; - values arrive in the order you sorted them — dates and numbers in their real order. The grid cannot re-sort a list that arrives in pieces;
- blanks are one row of their own at the top of the list (
hasBlanks), shown while the search box is empty; - Select all and Clear act on the whole list, with a search active and
with pieces not loaded. The selection is kept as "everything except these" or
"only these", so ticking a few values out of millions makes a short filter, not
a million-value one. "Everything except" becomes a
notincondition (see Filtering); "only these" aninas before. Reopening the popup reads the ticks back from the column's filter.
An older source that ignores skip and take and answers an array keeps the
single list — nothing to change. @kanunilabs/datagrid-server answers the paged
request (and createRestDataSource sends it: ?distinct=<column>&skip=0&take=200&search=…).
Make the list follow the grid. By default the list is the whole column, so
unticking a value never makes it vanish. Set remote.distinctFollowsSearch and
each request also carries filter (the other columns' filters — this column's own
is left out) and searchText (the quick search): the list then holds the values
still reachable, and is asked again when those change.
<DataGrid remote={{ distinctFollowsSearch: true }} dataSource={orders} /* … */ />
Totals
Ask for footer totals by reading options.summaries and returning
result.summaries, keyed "columnId:type":
// options.summaries → [{ columnId: 'revenue', type: 'sum' }]
return {
rows,
totalCount,
summaries: { 'revenue:sum': 1_284_500, 'id:count': 8_412 },
};
Two things worth knowing:
- A custom aggregation never reaches you.
type: 'custom'is a JavaScript function on the client, and your server has no way to run it. A grid whose only aggregation is custom therefore sends nothing and shows an empty footer on a remote source — the honest answer rather than a wrong number. - Totals belong to the query, not to a block. Returning them on every
response is fine (the last wins), and so is returning them only when
skip === 0. What must not happen is answering a new filter with the old filter's totals; the grid discards what it holds the moment the query changes precisely so a stale number cannot sit under fresh rows.
Grouping on the server
Enterprise. EnterpriseDataGrid / createEnterpriseGrid.
With group set, groupKeys says which level is being asked for: its length
is the depth. Given group: [region, category]:
groupKeys: []→ return the regions, asgroupsgroupKeys: ['Berlin']→ return Berlin's categories, asgroupsgroupKeys: ['Berlin', 'Toys']→ return the data rows, asrows
A group row carries its own count and, optionally, its aggregates:
return {
rows: [], // required by the type; a group level answers with `groups`
totalCount: 12, // children at THIS level
groups: [
{ value: 'Berlin', count: 1_204, aggregates: { 'revenue:sum': 91_400 } },
],
};
options.summaries arrives with every grouping level, not only the top
one: it says which aggregates the group rows carry, so 'Berlin''s categories
get their totals as well. The footer is read from the top level's answer
only, so a server that also totals the sub-level it was asked about does no
harm. The data rows inside the last level are asked for without it.
count is the data rows underneath at any depth — what the header shows.
totalCount is the number of children at this level, which is what the grid
pages through. They are different numbers and mixing them up produces a group
that reports thousands of rows and scrolls twelve.
Expand all (the group panel's button, or controller.expandAllGroups())
does not download the table. Groups open as they arrive, and a group asks for
its children only when it reaches the screen: roughly one request per group on
or just below it, however many groups the server has.
A tree on the server
With tree.hasChildren, load gets parentKey. It is null for the top
level, and otherwise the key of the row being opened. Return that level's rows
in rows and their number in totalCount; sort, filter and skip / take
apply within the level. See
Master-detail & tree data.
Typing while the server thinks
The filter row debounces on a remote source (200 ms by default), so a word
typed in one go is one request rather than one per letter. The grid also shows
its loading overlay for anything slower than a moment. It cannot cancel a
request already in flight — load is not handed an abort signal — but it drops
any answer that arrives for a query that has since changed, so a slow early
response never overwrites a newer one.
When a load fails
If load rejects — the network dropped, the server answered with an error —
the rows of that block do not keep pulsing as loading rows. Each of them says
Couldn't load these rows and carries a Retry button, so the message is
in view wherever the reader scrolled to. The rows the grid already had stay
where they are, and the dataError event reports the error.
A failed block is not asked for again on its own, so a server that is down is not hit again on every scroll. Retry asks for exactly the blocks that failed — the button does it, and so does the controller:
// After the connection comes back
window.addEventListener('online', () => controller.retryFailedLoads());
controller.isRowLoadFailed(index) tells whether a row in the view has nothing
to show because its load failed, if you draw your own message. When the very first request fails there are no rows
yet, so the grid shows one failed row to hold the message and the button. A
changed sort, filter or search starts over, failures included. The same applies
to a group's rows under server-side grouping and to a level of a server tree.
Refreshing when the server's data changes
The grid caches what it has fetched. When the data changes on the server — another user saved, a job finished — tell it to ask again:
controller.invalidate();
// A dashboard that polls: refresh every 10 seconds without the loading overlay
setInterval(() => controller.invalidate({ background: true }), 10_000);
The rows on screen stay until the new ones arrive. Only the blocks on screen
are asked for again, plus the first one, which carries the row count; under
server-side grouping, the top level and the open groups on screen. That is why
there is no call to refresh a single group: a full refresh already costs only
what is on screen. If the refresh fails, the rows keep their last data rather
than turning into Retry rows, dataError reports the error, and the part that
failed is asked for again by the next refresh or retryFailedLoads() — not on
every scroll.
background: true drops the overlay only; the busyChanged event still fires,
with background: true, if you want a quieter sign of your own.
Rows pushed by the server — the viewport model
Enterprise. Everything above asks: the grid requests blocks and waits
for them. For data that changes on its own — prices, an order book, a
monitoring screen — the server should instead push the rows on screen and
every change to them. That is viewportDatasource:
const feed: ViewportDatasource<Quote> = {
init({ setRowCount, setRowData }) {
socket.on('count', setRowCount);
// { 120: {...}, 121: {...} } — row index → row, any time
socket.on('rows', setRowData);
},
setViewportRange(first, last) {
socket.send({ subscribe: [first, last] }); // and drop the old range
},
setQuery({ sort, filter, searchText }) {
socket.send({ query: { sort, filter, searchText } });
},
destroy() {
socket.close();
},
};
<EnterpriseDataGrid dataSource={[]} viewportDatasource={feed} rowKey="symbol" columns={columns} />
The grid calls init once with three functions: setRowCount(n) sizes the
scrollbar, setRowData(rows) puts rows at their indexes (an object or a Map,
the first answer for a range or a change later), getRow(i) reads what it
holds. It then tells the source which rows are on screen with
setViewportRange(first, last) — a screen either side included, so a scroll
lands on rows that are already there, and only the latest range once the
scrolling stops moving. Rows that leave the range are dropped: the source stops
keeping them current, so the grid does not keep them either.
The source owns the order. The grid's sort, filter and search arrive in
setQuery (once before the first range, then on every change); the rows held
are dropped, and the source answers with the new count and the rows of the
range. Without setQuery the grid's sort and filter do nothing.
What it does not do: rows cannot be grouped (the source sends flat rows), and an export holds the rows on screen rather than paging through the result. A Community grid refuses the option with an error rather than showing an empty grid.
What stays client-side
Some things never become part of a query:
comparatorandexternalFilterare JavaScript functions, and a function cannot be sent to your server. On a remote source the grid does not apply them at all — the order and the rows are whateverloadreturns. Put that logic in the endpoint.- Selection, focus, editing state and column layout are view state; they never round-trip.
Export does reach the server: it covers the whole filtered result, so the
grid pages through the source to build the file, and a large export is as slow
as your endpoint is. It is capped at 100,000 rows by default
(remote.exportMaxRows); above that the export fails with a message naming the
limit instead of writing a truncated file. For larger results use the
streamed export (stream: true)
with exportMaxRows: Infinity; a source can also hand the rows over its own way
with exportRows.
Local or remote, same component
Nothing else in your code changes. Grouping, filtering, totals, selection,
theming and the event surface are the same props and the same events either way
— the differences above are the exceptions — so a grid can
start on an array and move to a DataSource when the data outgrows the tab —
without a rewrite.