Paged source

A page at a time

The paged source is the right fit when the data lives behind an endpoint that paginates and you want the grid to fetch it lazily. It loads blocks of pageSize rows, default a hundred, as the viewport reaches them, caches what it holds, and evicts the least recently used blocks outside the viewport so a long scroll does not grow without bound. Rows in a block that has not arrived report themselves as not loaded, so the grid draws skeleton cells rather than blanks while the request is in flight.

createGrid(el, {
  columns,
  rowKey: 'id',
  source: {
    mode: 'paged',
    pageSize: 100,        // rows per block; the default
    async fetch(req) {
      const res = await api.rows({
        offset: req.range.start,
        limit:  req.range.end - req.range.start,
        sort:   req.sort,      // [{ col, dir }, …]
        filters: req.filters,  // the condition tree
        quick:  req.quick,
      }, { signal: req.signal });   // a superseded request aborts itself
      return { rows: res.rows, total: res.total };   // total is optional
    },
  },
});

Sort and filter go to the server

This is the point worth being precise about. Because the grid holds only a window at any moment, filtering or sorting that window in the browser would be wrong: the rows that belong on page one might sit on page nine. So sorting and filtering are handed to the server, and changing either invalidates every cached block and re-queries, because the server may now return an entirely different window for the same range. Your fetch callback receives the sort array and the filter condition tree in the published format, the same shape you would have written by hand, and it is your endpoint's job to apply them.

A configured host filter is never sent to the server and warns once if you set one, because silently filtering only the fetched window would produce wrong counts and wrong rows. The grid refuses to trade a correct answer for a convenient one.

The total makes the scrollbar exact

Return a total and the scrollbar switches from open-ended to exact, sized to the real number of matching rows. Omit it and the source stays in unknown-length mode, extending as it discovers more and settling once a short block proves the end. Either works; the total simply buys an accurate scrollbar from the first request rather than one that grows as the reader scrolls.

Paged or remote?

The paged source is the simpler of the two server modes: a flat list, a page per request, sort and filter pushed down. Reach for the remote source instead when you want the server to group, total and pivot as well, fetching one group level at a time. If your data lives behind a query engine rather than a hand-written endpoint, a pushdown adapter can write the translation for you.

See it running: the paged source. For the full set of options, start from connect your data.