Server-Side Plugin

The Server-Side plugin enables virtual scrolling with lazy loading from a remote API. It’s designed for large datasets (10,000+ rows) where loading all data upfront would be impractical or slow.

When to Use This Plugin

Scenario	Recommended Approach
< 1,000 rows	Load all data upfront (no plugin needed)
1,000 - 10,000 rows	Consider based on network speed and data complexity
10,000+ rows	Use ServerSidePlugin
Infinite scroll / pagination	Use ServerSidePlugin
Data changes frequently on server	Use ServerSidePlugin with refresh()

Key Features

• Block-based fetching: Loads only visible rows plus a buffer
• LRU caching: Keeps recently viewed blocks in memory
• Automatic prefetching: Loads next blocks as user scrolls
• Concurrent request limiting: Prevents overwhelming the server
• Loading placeholders: Shows loading state for pending rows
• Integration with sorting/filtering: Works with sortHandler and filterHandler

Installation

import '@toolbox-web/grid/features/server-side';

Basic Usage

The feature requires a data source that implements the getRows method. Set it via getPluginByName('serverSide') after the grid is ready:

Vanilla JS

import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/server-side';

const dataSource = {
  async getRows(params) {
    // params: { startRow, endRow, sortModel, filterModel }
    const response = await fetch(`/api/data?start=${params.startRow}&end=${params.endRow}`);
    const data = await response.json();
    return {
      rows: data.rows,
      totalRowCount: data.total, // Required for scroll height calculation
    };
  },
};

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
  ],
  features: {
    serverSide: { pageSize: 50 },
  },
};

// Set data source after grid is ready
grid.ready().then(() => {
  const plugin = grid.getPluginByName('serverSide');
  plugin.setDataSource(dataSource);
});

React

import '@toolbox-web/grid-react/features/server-side';
import { DataGrid, useGrid } from '@toolbox-web/grid-react';
import { useEffect } from 'react';

const dataSource = {
  async getRows(params) {
    const response = await fetch(`/api/data?start=${params.startRow}&end=${params.endRow}`);
    const data = await response.json();
    return { rows: data.rows, totalRowCount: data.total };
  },
};

function ServerSideGrid() {
  const { ref, element } = useGrid();

  useEffect(() => {
    if (element) {
      element.ready().then(() => {
        const plugin = element.getPluginByName('serverSide');
        plugin?.setDataSource(dataSource);
      });
    }
  }, [element]);

  return (
    <DataGrid
      ref={ref}
      columns={[
        { field: 'id', header: 'ID' },
        { field: 'name', header: 'Name' },
        { field: 'email', header: 'Email' },
      ]}
      serverSide={{ pageSize: 50 }}
      style={{ height: '400px' }}
    />
  );
}

Vue

<script setup>
import '@toolbox-web/grid-vue/features/server-side';
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';
import { ref, onMounted } from 'vue';

const gridRef = ref(null);

const dataSource = {
  async getRows(params) {
    const response = await fetch(`/api/data?start=${params.startRow}&end=${params.endRow}`);
    const data = await response.json();
    return { rows: data.rows, totalRowCount: data.total };
  },
};

onMounted(async () => {
  const grid = gridRef.value?.element;
  await grid?.ready();
  grid?.getPluginByName('serverSide')?.setDataSource(dataSource);
});
</script>

<template>
  <TbwGrid ref="gridRef" :server-side="{ pageSize: 50 }" style="height: 400px">
    <TbwGridColumn field="id" header="ID" />
    <TbwGridColumn field="name" header="Name" />
    <TbwGridColumn field="email" header="Email" />
  </TbwGrid>
</template>

Angular

// Feature import - enables the [serverSide] input
import '@toolbox-web/grid-angular/features/server-side';

import { Component, viewChild, ElementRef } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig, GridElement } from '@toolbox-web/grid';

@Component({
  selector: 'app-server-side-grid',
  imports: [Grid],
  template: `
    <tbw-grid
      #grid
      [columns]="columns"
      [serverSide]="{ pageSize: 50 }"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class ServerSideGridComponent {
  gridRef = viewChild<ElementRef<GridElement>>('grid');

  columns: ColumnConfig[] = [
    { field: 'id', header: 'ID' },
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
  ];

  private dataSource = {
    getRows: async (params: any) => {
      const response = await fetch(`/api/data?start=${params.startRow}&end=${params.endRow}`);
      const data = await response.json();
      return { rows: data.rows, totalRowCount: data.total };
    },
  };

  ngAfterViewInit() {
    this.gridRef()?.nativeElement.ready().then(() => {
      const plugin = this.gridRef()?.nativeElement.getPluginByName('serverSide');
      plugin?.setDataSource(this.dataSource);
    });
  }
}

Demos

Virtual Scroll Mode

SERVER

Page size Rows fetched per request

50

Show source

Paging Mode

Show source

Server-Side Sorting

Show source

Use the sortHandler config option for async sorting. When a user clicks a sortable column header, your handler is called instead of the built-in sorting logic. This is ideal for large datasets where sorting should happen on the backend.

grid.gridConfig = {
  columns: [...],
  sortHandler: async (rows, sortState, columns) => {
    // sortState: { field: 'name', direction: 1 } // 1 = asc, -1 = desc
    const response = await fetch(
      `/api/data?sort=${sortState.field}&dir=${sortState.direction === 1 ? 'asc' : 'desc'}`
    );
    return response.json();
  },
};

The handler receives:

• rows - Current row array (may be useful for optimistic updates)
• sortState - { field: string, direction: 1 | -1 }
• columns - Column configurations (access sortComparator if needed)

Return the sorted array directly or a Promise that resolves to it.

Server-Side Filtering

For server-side filtering, use the FilteringPlugin’s async handlers. See the Filtering Plugin documentation for details on valuesHandler and filterHandler.

Configuration Options

See ServerSideConfig for the full list of options and defaults.

TypeScript Interfaces

• ServerSideDataSource — Data source contract with getRows() method
• GetRowsParams — Parameters passed to getRows() (startRow, endRow, sortModel, filterModel)
• GetRowsResult — Return type with rows and totalRowCount

Programmatic API

const plugin = grid.getPluginByName('serverSide');

plugin.setDataSource(newDataSource);  // Set or replace the data source
plugin.refresh();                      // Reload current viewport from server
plugin.purgeCache();                   // Clear all cached blocks
plugin.getTotalRowCount();             // Get server-reported total row count
plugin.isRowLoaded(index);             // Check if a specific row is in cache
plugin.getLoadedBlockCount();          // Number of blocks currently cached

Architecture: How It Works

The plugin uses a block-based caching strategy:

┌────────────────────────────────────────────────┐
│  Total Dataset: 100,000 rows (on server)       │
├────────────────────────────────────────────────┤
│  Block 0: rows 0-99     [CACHED]               │
│  Block 1: rows 100-199  [CACHED]               │
│  Block 2: rows 200-299  [LOADING...]           │
│  Block 3: rows 300-399  [NOT LOADED]           │
│  ...                                           │
│  Block 999: rows 99900-99999 [NOT LOADED]      │
└────────────────────────────────────────────────┘

Scroll triggers:

1. onScroll event fires
2. Plugin calculates which blocks are needed for the visible viewport
3. Missing blocks are requested from the data source
4. requestRender() is called when data arrives
5. Grid re-renders with new data

Loading state: Rows that haven’t loaded yet are represented with placeholder objects:

{ __loading: true, __index: 42 }

You can detect loading rows via a custom cell renderer and style them accordingly:

columns: [{
  field: 'name',
  renderer: (value, row) => row.__loading ? '<span class="loading">Loading…</span>' : value,
}]

Combining with Other Plugins

The ServerSidePlugin works well with:

Plugin	Integration
FilteringPlugin	Use filterHandler for server-side filtering
MultiSortPlugin	Use sortHandler for server-side sorting
SelectionPlugin	Works normally - selection state is client-side
EditingPlugin	Works normally - edits are local until you sync
ExportPlugin	Only exports cached rows by default

Note: RowGroupingPlugin and TreePlugin are not recommended with server-side data as they require all data to be present for grouping calculations.

See Also

• Filtering — Client-side filtering
• Multi-Sort — Client-side multi-sort
• Export — Export grid data
• Common Patterns — Full application recipes
• Plugins Overview — Plugin compatibility and combinations