GitHub - warper-org/warper: Ultra-fast React virtualization library powered by Rust and WebAssembly

4 min read Original article ↗

npm version npm downloads License Bundle Size

Ultra-fast React virtualization library powered by Rust and WebAssembly

10,000,000+ rows | 120+ FPS | O(1) lookups | Cross-browser

Live Demo | Documentation | Examples

Features

  • 120+ FPS - Smooth scrolling performance even with millions of items
  • 10M+ Items - Handle massive datasets without breaking a sweat
  • O(1) Uniform Operations - Instant calculations for fixed-height items
  • O(log n) Variable Sizes - Fenwick tree for dynamic heights
  • GPU Acceleration - CSS transform3d() and contain: strict
  • Zero-Copy Transfers - Direct WASM-to-JS typed arrays
  • Adaptive Overscan - Smart prefetching based on scroll velocity
  • Skip-Render Optimization - Only re-render when range changes
  • 8x Loop Unrolling - Maximum instruction throughput
  • Pre-allocated Pools - Zero allocation in scroll hot path
  • Cross-Browser - Chrome, Firefox, Safari, Edge support
  • ~8.7KB Bundle - Tree-shakable, minimal footprint (8.7kB gzipped)
  • TypeScript First - Full type safety

Installation

npm install @itsmeadarsh/warper
# or
yarn add @itsmeadarsh/warper
# or
pnpm add @itsmeadarsh/warper
# or
bun add @itsmeadarsh/warper

Quick Start

Using the Hook (Recommended)

import { useVirtualizer } from '@itsmeadarsh/warper';

function MyList() {
  const { scrollElementRef, range, totalHeight } = useVirtualizer({
    itemCount: 1_000_000,  // 1 million items!
    estimateSize: () => 50, // Fixed row height
    overscan: 5,
  });

  return (
    <div ref={scrollElementRef} style={{ height: 500, overflow: 'auto' }}>
      <div style={{ height: totalHeight, position: 'relative' }}>
        {range.items.map((index, i) => (
          <div
            key={index}
            style={{
              position: 'absolute',
              top: 0,
              transform: `translateY(${range.offsets[i]}px)`,
              height: range.sizes[i],
              width: '100%',
            }}
          >
            Row {index}
          </div>
        ))}
      </div>
    </div>
  );
}

Using the Component

import { WarperComponent } from '@itsmeadarsh/warper';

function MyList() {
  return (
    <WarperComponent
      itemCount={1_000_000}
      estimateSize={() => 50}
      height={500}
      overscan={5}
    >
      {(index) => (
        <div style={{ padding: 16 }}>
          Row {index}
        </div>
      )}
    </WarperComponent>
  );
}

API Reference

useVirtualizer<T>(options)

The core hook for virtualization.

Options

Property Type Default Description
itemCount number required Total number of items
estimateSize (index: number) => number required Function returning item height
overscan number 5 Extra items to render above/below
horizontal boolean false Horizontal scroll mode
height number | string '100%' Container height

Returns

Property Type Description
scrollElementRef RefObject Attach to scroll container
range VirtualRange Current visible range data
totalHeight number Total scrollable height
isLoading boolean WASM loading state
error Error | null Error if initialization failed
scrollToIndex (index, behavior?) => void Scroll to specific index
scrollToOffset (offset, behavior?) => void Scroll to pixel offset

VirtualRange

interface VirtualRange {
  startIndex: number;    // First visible index
  endIndex: number;      // Last visible index
  items: number[];       // Array of visible indices
  offsets: number[];     // Y-offset for each item
  sizes: number[];       // Height of each item
  totalHeight: number;   // Total content height
  velocity: number;      // Current scroll velocity
}

<WarperComponent>

A ready-to-use virtualized list component.

interface WarperComponentProps<T> {
  itemCount: number;
  estimateSize: (index: number) => number;
  children: (index: number) => React.ReactNode;
  overscan?: number;
  height?: number | string;
  horizontal?: boolean;
  className?: string;
  style?: CSSProperties;
  onRendered?: () => void;
  loadingPlaceholder?: React.ReactNode;
  errorPlaceholder?: (error: Error) => React.ReactNode;
}

Browser Support

Browser Minimum Version
Chrome 89+
Firefox 89+
Safari 15+
Edge 89+
Opera 75+
Chrome Android Latest
Safari iOS 15+

Warper uses:

  • WebAssembly.compileStreaming (with fallback)
  • CSS contain property
  • transform3d for GPU layers
  • Passive scroll listeners

Comparison

Feature Warper react-window react-virtuoso @tanstack/virtual
WASM Core Yes No No No
10M+ Items Yes Limited Limited Yes
120+ FPS Yes Yes Yes Yes
O(1) Fixed Yes No No No
O(log n) Variable Yes No No No
Zero-Copy Arrays Yes No No No
GPU Acceleration Yes Limited Limited Limited
Adaptive Overscan Yes No No No
TypeScript Yes Yes Yes Yes
Bundle Size ~6KB ~6KB ~25KB ~12KB

Development

# Install dependencies
bun install

# Build WASM (requires Rust + wasm-pack)
cd wasm/rust && wasm-pack build --target web --release

# Run examples
bun run example:one-million-rows
bun run example:list
bun run example:grid

Building from Source

# Prerequisites
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install wasm-pack

# Build WASM
cd wasm/rust && wasm-pack build --target web --release

# Build TypeScript
bun run build

Examples

Explore the repository to see Warper in action:

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

AI Assistance

Need help with Warper? You can use Context7 MCP to get up-to-date documentation and code examples directly in your AI coding assistant. Context7 provides real-time access to Warper's API reference and usage patterns.

License

MIT License - see LICENSE for details.

Warper - Ultra-Fast React Virtualization

Rust/WASM | 120+ FPS | O(1) & O(log n)

GitHub | npm | Documentation