Simple Virtualization for React

Overview

This package provides three powerful virtualization components for React applications:

1. Virtualization: A core component for rendering large lists efficiently
2. VirtualizationTable: A specialized component for handling large datasets in tabular format
3. VirtualizationGrid: A component for efficiently rendering large two-dimensional grids

All components are designed to optimize performance by rendering only the visible portions of your content.

Features

Core Virtualization Features

• Dynamic viewport rendering
• Variable height item support
• Efficient scroll handling with requestAnimationFrame
• Support for multiple content types:
  • String content
  • React Elements
  • Function components
  • Complex components with props
• Customizable overscan (buffer) zones
• Automatic height calculation and caching
• Smooth scrolling optimization
• Isomorphic layout effect support
• Error boundary protection for item rendering
• Compatible with older React versions via polyfills
• Binary search for efficient item positioning
• Scroll direction-aware rendering optimization

VirtualizationTable Features

• Sortable columns with multiple states (asc/desc/none)
• Customizable header, row, and footer components
• Synchronized horizontal scrolling across sections
• Dynamic column width calculations
• Responsive design support
• Custom styling for all table sections
• Row virtualization for optimal performance
• Support for distributed footer layouts
• Built-in ResizeObserver integration
• TypeScript support with comprehensive types
• Smooth scroll synchronization between sections
• Advanced sorting with null state support
• Optimized scroll event handling
• Automatic column width distribution

VirtualizationGrid Features

• Efficient rendering of large two-dimensional data sets
• Independent row and column virtualization
• Customizable cell dimensions
• Dynamic viewport calculation
• Optimized scroll performance
• Flexible cell rendering API
• Customizable styling for grid and cells
• Built-in overscan support for smooth scrolling
• Efficient memory usage for large datasets
• Responsive to container size changes

Installation

1npm install simple-virtualization
2# or
3yarn add simple-virtualization

Example App

The package includes a comprehensive example application that demonstrates all three virtualization components. The example app showcases various implementation patterns and features:

Virtualization Component Example

• Handles mixed content types including:
  • HTML strings
  • React components
  • Functional components
  • Component configurations with props
• Demonstrates custom styling with CSS-in-JS
• Shows proper component composition
• Implements efficient content rendering strategies
• Supports dynamic height calculations
• Example items include various layouts:
  • Simple text content
  • Complex grid layouts
  • Image placeholders
  • Nested components

VirtualizationTable Example

• Implements a full-featured data table with:
  • 12 columns with different data types
  • Custom column widths
  • Sortable columns with visual indicators
  • Status indicators with color coding
  • Custom cell rendering
  • Comprehensive footer with statistics
• Features advanced user data management:
  • 1000+ mock user records
  • Multiple data types (text, dates, numbers)
  • Status tracking
  • Performance metrics
  • Team information
• Demonstrates sophisticated styling:
  • Hover effects
  • Status indicators
  • Responsive layout
  • Custom header/footer designs

VirtualizationGrid Example

• Showcases a 1000x1000 grid implementation
• Features:
  • Dynamic cell background colors
  • Interactive cell selection
  • Custom content generation
  • Responsive layout
  • Efficient rendering of large datasets
• Implements:
  • Cell click handlers
  • Visual selection feedback
  • Custom cell styling
  • Dynamic content generation
  • Performant scroll handling

Running the Example

1npm run example

The example app demonstrates:

• Basic and advanced usage of all three components
• Table virtualization with sorting and custom column widths
• Grid virtualization with interactive features
• Dynamic height calculations
• Custom styling examples
• Performance optimization techniques
• Different types of content rendering
• Responsive design patterns
• Integration with TypeScript

Basic Usage

Virtualization Component

1import { Virtualization } from 'simple-virtualization';
2
3function SimpleList() {
4  const items = Array.from({ length: 10000 }, (_, i) => `Item ${i}`);
5
6  return (
7    <Virtualization
8      items={items}
9      className="virtual-list"
10      estimatedItemHeight={40}
11      overscanCount={5}
12    />
13  );
14}

VirtualizationTable Component

1import { VirtualizationTable } from 'simple-virtualization';
2
3function DataTable() {
4  const data = Array.from({ length: 10000 }, (_, i) => ({
5    id: i,
6    name: `Item ${i}`,
7    value: Math.random() * 100
8  }));
9
10  return (
11    <VirtualizationTable
12      data={data}
13      Header={({ onSort, sortState }) => (
14        <div className="header-row">
15          <div onClick={() => onSort('name')}>Name</div>
16          <div onClick={() => onSort('value')}>Value</div>
17        </div>
18      )}
19      Row={({ item, index }) => (
20        <>
21          <div>{item.name}</div>
22          <div>{item.value.toFixed(2)}</div>
23        </>
24      )}
25      columnWidths={['200px', '150px']}
26      tableHeight="500px"
27    />
28  );
29}

VirtualizationGrid Component

1import { VirtualizationGrid } from 'simple-virtualization';
2
3function DataGrid() {
4  return (
5    <VirtualizationGrid
6      dimensions={{
7        rowCount: 1000,
8        columnCount: 1000
9      }}
10      estimatedColumnWidth={100}
11      estimatedRowHeight={50}
12      overscanCount={2}
13      renderCell={(rowIndex, columnIndex) => (
14        `Cell ${rowIndex},${columnIndex}`
15      )}
16      className="virtual-grid"
17      style={{ height: '500px' }}
18    />
19  );
20}

Component Props

Virtualization Props

1interface VirtualizationProps {
2  items: ReactComponentOrElement[];
3  className?: string;
4  itemClassName?: string;
5  style?: CSSProperties;
6  itemStyle?: CSSProperties;
7  overscanCount?: number;
8  initialRenderCount?: number;
9  estimatedItemHeight?: number;
10}

VirtualizationTable Props

1interface VirtualizationTableProps<T> {
2  data: T[];
3  Header: React.ComponentType<{
4    onSort: (column: string) => void;
5    sortState: SortState;
6  }>;
7  Footer?: React.ComponentType;
8  Row: React.ComponentType<{ item: T; index: number }>;
9  style?: React.CSSProperties;
10  headerStyle?: React.CSSProperties;
11  footerStyle?: React.CSSProperties;
12  rowStyle?: React.CSSProperties;
13  tableHeight?: string | number;
14  estimatedRowHeight?: number;
15  overscanCount?: number;
16  columnWidths?: string[];
17  footerDistributed?: boolean;
18  defaultSortColumn?: string;
19  defaultSortDirection?: SortDirection;
20}

VirtualizationGrid Props

1interface VirtualizationGridProps {
2  dimensions: {
3    rowCount: number;
4    columnCount: number;
5  };
6  estimatedColumnWidth?: number;
7  estimatedRowHeight?: number;
8  overscanCount?: number;
9  renderCell: (rowIndex: number, columnIndex: number) => React.ReactNode;
10  className?: string;
11  style?: CSSProperties;
12  cellClassName?: string;
13  cellStyle?: CSSProperties;
14}

Advanced Features

Dynamic Height Calculation

Both list and table components automatically measure and adapt to varying content heights:

1<Virtualization
2  items={items}
3  estimatedItemHeight={50}  // Initial estimate
4  // Heights are automatically measured and cached
5/>

Grid Cell Customization

1<VirtualizationGrid
2  dimensions={{ rowCount: 100, columnCount: 100 }}
3  cellStyle={{
4    border: '1px solid #ccc',
5    padding: '8px'
6  }}
7  renderCell={(row, col) => (
8    <div className="custom-cell">
9      {/* Custom cell content */}
10    </div>
11  )}
12/>

Table Sorting and Column Management

1<VirtualizationTable
2  defaultSortColumn="name"
3  defaultSortDirection="asc"
4  columnWidths={['200px', '150px', '100px']}
5  // Columns will resize proportionally when container width changes
6/>

Performance Optimizations

Virtualization Component

• Binary search for efficient item positioning
• Cached height measurements
• Scroll direction-aware rendering
• Minimal DOM updates
• RequestAnimationFrame for smooth scrolling
• Stable callback optimizations

VirtualizationTable Component

• Virtualized row rendering
• Optimized scroll synchronization
• Efficient column width calculations
• Debounced resize handling
• Memoized sorting operations

VirtualizationGrid Component

• Efficient viewport calculation
• Minimal cell re-rendering
• Optimized scroll handling
• Memory-efficient cell management
• Smart overscan implementation

Browser Support

Supports all modern browsers with these features:

• ResizeObserver API
• RequestAnimationFrame
• CSS Grid
• Flexbox
• IntersectionObserver (optional)

TypeScript Support

All components include comprehensive TypeScript definitions:

1// Example type usage
2type YourDataType = {
3  id: number;
4  name: string;
5  // ...
6};
7
8<VirtualizationTable<YourDataType>
9  data={yourData}
10  // TypeScript will ensure type safety
11/>

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License

Support

For issues and feature requests, please use the GitHub issue tracker.