Documentation

Server-side data

Try it live:

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

FieldWhat it is
skip / takeThe block being asked for.
sortColumn ids and directions, in priority order.
filterA serializable filter AST — the same tree the worker gets.
searchTextThe quick-search box, if the grid has one.
group / groupKeysRemote grouping; see below.
summariesFooter 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's LOWER folds only ASCII unless it is built with ICU.
  • Sort order of text: your database's collation.
  • Quick search looks in string columns. Set searchable: true on 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 totalCount long (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 notin condition (see Filtering); "only these" an in as 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

Try it live:

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, as groups
  • groupKeys: ['Berlin'] → return Berlin's categories, as groups
  • groupKeys: ['Berlin', 'Toys'] → return the data rows, as rows

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

Try it live:

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:

  • comparator and externalFilter are 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 whatever load returns. 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.