Active Grid

Virtualization - Active Grid

Overview

Virtualization renders only visible rows in the viewport, dramatically improving performance for large datasets. The ActiveGrid automatically enables virtualization for datasets exceeding 1,000 rows.

How It Works

Instead of rendering all rows in the DOM, virtualization:

Calculates which rows are visible in the viewport
Renders only those rows plus a small buffer
Updates rendered rows as the user scrolls
Reuses DOM elements for optimal performance

This allows the grid to handle datasets with 100,000+ rows smoothly.

Automatic Virtualization

Virtualization automatically enables when row count exceeds the threshold:

<ActiveGrid
  columns={columns}
  data={largeDataset} // 5,000 rows
  // Virtualization automatically enabled
  {...}
/>

Configuration

enableVirtualization

Type: boolean
Default: false
Description: Force enable virtualization regardless of row count

<ActiveGrid
  enableVirtualization={true}
  columns={columns}
  data={data}
  {...}
/>

virtualizationThreshold

Type: number
Default: 1000
Description: Row count threshold for automatic virtualization

<ActiveGrid
  virtualizationThreshold={500} // Enable at 500 rows
  columns={columns}
  data={data}
  {...}
/>

virtualContainerHeight

Type: number
Description: Container height in pixels for virtualized rendering

<ActiveGrid
  virtualContainerHeight={600}
  enableVirtualization={true}
  columns={columns}
  data={data}
  {...}
/>

When virtualContainerHeight is not specified, the grid calculates height based on available space.

When to Use Virtualization

Use Virtualization For:

Datasets with 1,000+ rows
Infinite scroll implementations
Real-time data streams
Performance-critical applications
Mobile devices with limited resources

Don't Use Virtualization For:

Small datasets (<100 rows)
Print layouts
Static reports
When all rows must be visible simultaneously

Performance Impact

Without Virtualization

10,000 rows: ~2-3 seconds initial render
DOM nodes: 10,000+ elements
Memory: ~50-100 MB
Scroll: Laggy and janky

With Virtualization

10,000 rows: ~100-200ms initial render
DOM nodes: ~20-30 elements
Memory: ~5-10 MB
Scroll: Smooth 60 FPS

Client-Side Example

Server-Side Example

Virtualization works seamlessly with server-side pagination:

Variable Row Heights

Virtualization works best with fixed row heights. Variable row heights can cause scroll position issues.

If you need variable heights, consider:

Using autoHeight sparingly
Estimating average row height
Implementing custom virtualization logic

Customizing Row Height

Set consistent row height for optimal virtualization:

Overscan

The grid renders additional rows above and below the viewport (overscan) to prevent flashing during scroll. This is automatically calculated but optimized for smooth scrolling.

Infinite Scroll

Combine virtualization with server-side mode for infinite scroll:

Performance Optimization

Optimize Column Rendering

Optimize Data Processing

Avoid Re-renders

Debugging Virtualization

Check if virtualization is active:

Common Issues

Issue: Scroll Position Jumps

Solution: Ensure consistent row heights

Issue: Blank Rows During Fast Scrolling

Solution: This is normal during very fast scrolling. Increase overscan if needed (handled automatically).

Issue: Performance Still Poor

Solutions:

Reduce column count
Simplify cell renderers
Use memoization
Enable server-side mode
Reduce page size

Best Practices

✅ DO

Use fixed row heights
Enable for large datasets
Combine with server-side mode
Memoize expensive operations
Test scroll performance
Monitor memory usage

❌ DON'T

Don't use with <100 rows
Don't use variable row heights
Don't render complex cells unnecessarily
Don't forget to memoize
Don't disable when needed
Don't ignore scroll performance

Memory Management

Virtualization significantly reduces memory usage:

Monitor memory in Chrome DevTools:

Open DevTools → Performance
Record while scrolling
Check memory usage in Memory panel

Browser Support

Virtualization works in all modern browsers:

Chrome/Edge 90+
Firefox 88+
Safari 14+
Mobile browsers (iOS 14+, Android 10+)

Complete Example

Performance Metrics

Target performance with virtualization:

Initial render: <200ms for 100,000 rows
Scroll FPS: 60 FPS
Memory: <20 MB for 100,000 rows
Page change: <50ms

TypeScript

<ActiveGrid
  mode="server"
  fetchFn={async (params) => {
    const response = await api.getData({
      page: params.pageIndex,
      limit: params.pageSize,
    });
    return {
      data: response.data,
      totalCount: response.total,
    };
  }}
  columns={columns}
  pagination={{
    enabled: true,
    pageSizeOptions: [50, 100, 200],
  }}
  initialPageSize={100}
  enableVirtualization={true}
  {...}
/>

function InfiniteScrollTable() {
  const [pageSize] = useState(50);
  
  return (
    <ActiveGrid
      mode="server"
      fetchFn={async (params) => {
        const response = await api.getData({
          offset: params.pageIndex * params.pageSize,
          limit: params.pageSize,
        });
        return {
          data: response.data,
          totalCount: response.total,
        };
      }}
      columns={columns}
      initialPageSize={pageSize}
      enableVirtualization={true}
      virtualContainerHeight={800}
      pagination={{
        enabled: true,
        showButtons: false, // Hide pagination buttons
      }}
      {...}
    />
  );
}

// Memoize cell renderers
const columns: GridColumnDef<Data>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
    cell: memo(({ getValue }) => {
      return <span>{getValue()}</span>;
    }),
  },
];

// Memoize data transformations
const processedData = useMemo(() => {
  return rawData.map(item => ({
    ...item,
    computed: expensiveCalculation(item),
  }));
}, [rawData]);

<ActiveGrid data={processedData} {...} />

// Memoize columns
const columns = useMemo(() => [...], []);

// Memoize callbacks
const handleRowClick = useCallback((row) => {
  // Handle click
}, []);

<ActiveGrid
  columns={columns}
  data={data}
  onRowClick={handleRowClick}
  {...}
/>

import { useActiveGrid } from '@workspace/active-grid';

function DebugInfo() {
  const table = useActiveGrid();
  const rowModel = table.getRowModel();
  const virtualRows = table.getRowModel().rows;
  
  return (
    <div>
      <p>Total rows: {table.getRowCount()}</p>
      <p>Rendered rows: {virtualRows.length}</p>
      <p>Virtualization: {virtualRows.length < table.getRowCount() ? 'Active' : 'Inactive'}</p>
    </div>
  );
}

import { useMemo } from 'react';
import { ActiveGrid, GridColumnDef } from '@workspace/active-grid';

type Data = {
  id: string;
  name: string;
  value: number;
};

function LargeActiveGrid() {
  // Generate large dataset
  const data = useMemo(() => {
    return Array.from({ length: 50000 }, (_, i) => ({
      id: `row-${i}`,
      name: `Item ${i}`,
      value: Math.random() * 1000,
    }));
  }, []);
  
  const columns = useMemo<GridColumnDef<Data>[]>(() => [
    {
      accessorKey: 'id',
      header: 'ID',
      size: 100,
    },
    {
      accessorKey: 'name',
      header: 'Name',
      size: 200,
    },
    {
      accessorKey: 'value',
      header: 'Value',
      size: 120,
      meta: {
        cellAlign: 'right',
        valueFormatter: (value) => `$${value.toFixed(2)}`,
      },
    },
  ], []);
  
  return (
    <ActiveGrid
      columns={columns}
      data={data}
      enableVirtualization={true}
      virtualContainerHeight={700}
      settings={{
        rowHeight: 44,
      }}
      pagination={{
        enabled: true,
        pageSizeOptions: [50, 100, 200, 500],
      }}
      initialPageSize={100}
    />
  );
}

Virtualization