simple-virtualization

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

npm install simple-virtualization
# or
yarn 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

npm 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

import { Virtualization } from 'simple-virtualization';

function SimpleList() {
  const items = Array.from({ length: 10000 }, (_, i) => `Item ${i}`);

  return (
    <Virtualization
      items={items}
      className="virtual-list"
      estimatedItemHeight={40}
      overscanCount={5}
    />
  );
}

VirtualizationTable Component

import { VirtualizationTable } from 'simple-virtualization';

function DataTable() {
  const data = Array.from({ length: 10000 }, (_, i) => ({
    id: i,
    name: `Item ${i}`,
    value: Math.random() * 100
  }));

  return (
    <VirtualizationTable
      data={data}
      Header={({ onSort, sortState }) => (
        <div className="header-row">
          <div onClick={() => onSort('name')}>Name</div>
          <div onClick={() => onSort('value')}>Value</div>
        </div>
      )}
      Row={({ item, index }) => (
        <>
          <div>{item.name}</div>
          <div>{item.value.toFixed(2)}</div>
        </>
      )}
      columnWidths={['200px', '150px']}
      tableHeight="500px"
    />
  );
}

VirtualizationGrid Component

import { VirtualizationGrid } from 'simple-virtualization';

function DataGrid() {
  return (
    <VirtualizationGrid
      dimensions={{
        rowCount: 1000,
        columnCount: 1000
      }}
      estimatedColumnWidth={100}
      estimatedRowHeight={50}
      overscanCount={2}
      renderCell={(rowIndex, columnIndex) => (
        `Cell ${rowIndex},${columnIndex}`
      )}
      className="virtual-grid"
      style={{ height: '500px' }}
    />
  );
}

Component Props

Virtualization Props

interface VirtualizationProps {
  items: ReactComponentOrElement[];
  className?: string;
  itemClassName?: string;
  style?: CSSProperties;
  itemStyle?: CSSProperties;
  overscanCount?: number;
  initialRenderCount?: number;
  estimatedItemHeight?: number;
}

VirtualizationTable Props

interface VirtualizationTableProps<T> {
  data: T[];
  Header: React.ComponentType<{
    onSort: (column: string) => void;
    sortState: SortState;
  }>;
  Footer?: React.ComponentType;
  Row: React.ComponentType<{ item: T; index: number }>;
  style?: React.CSSProperties;
  headerStyle?: React.CSSProperties;
  footerStyle?: React.CSSProperties;
  rowStyle?: React.CSSProperties;
  tableHeight?: string | number;
  estimatedRowHeight?: number;
  overscanCount?: number;
  columnWidths?: string[];
  footerDistributed?: boolean;
  defaultSortColumn?: string;
  defaultSortDirection?: SortDirection;
}

VirtualizationGrid Props

interface VirtualizationGridProps {
  dimensions: {
    rowCount: number;
    columnCount: number;
  };
  estimatedColumnWidth?: number;
  estimatedRowHeight?: number;
  overscanCount?: number;
  renderCell: (rowIndex: number, columnIndex: number) => React.ReactNode;
  className?: string;
  style?: CSSProperties;
  cellClassName?: string;
  cellStyle?: CSSProperties;
}

Advanced Features

Dynamic Height Calculation

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

<Virtualization
  items={items}
  estimatedItemHeight={50}  // Initial estimate
  // Heights are automatically measured and cached
/>

Grid Cell Customization

<VirtualizationGrid
  dimensions={{ rowCount: 100, columnCount: 100 }}
  cellStyle={{
    border: '1px solid #ccc',
    padding: '8px'
  }}
  renderCell={(row, col) => (
    <div className="custom-cell">
      {/* Custom cell content */}
    </div>
  )}
/>

Table Sorting and Column Management

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

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:

// Example type usage
type YourDataType = {
  id: number;
  name: string;
  // ...
};

<VirtualizationTable<YourDataType>
  data={yourData}
  // TypeScript will ensure type safety
/>

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.