Skip to content

Virtualized List

Medium ~45 min

What you'll build

A VirtualList component that renders only the items visible in the viewport, using scroll position and fixed item height to compute the window.

Goals

  • Track scroll position with a ref and event
  • Compute the visible item range from scrollTop
  • Render only visible items with absolute positioning
  • Add a spacer to maintain scroll height

Prerequisites

  • useState and useRef
  • Absolute positioning in CSS
  • Scroll event handling

Steps

  1. 1

    Set up the container

    Create a div with a fixed height and overflow-y: auto. This is the scroll container. Track its scrollTop with a state and onScroll handler.

    Code
    function VirtualList({ items, itemHeight = 50, height = 400 }) {
      const [scrollTop, setScrollTop] = useState(0);
      return (
        <div
          style={{ height, overflowY: 'auto' }}
          onScroll={e => setScrollTop(e.currentTarget.scrollTop)}
        >
          {/* items go here */}
        </div>
      );
    }

    Expected result

    A scrollable container that updates scrollTop on scroll.

  2. 2

    Compute the visible window

    From scrollTop, compute the start index (floor(scrollTop / itemHeight)) and the number of visible items (ceil(height / itemHeight)). Add an overscan buffer.

    Code
    const startIndex = Math.floor(scrollTop / itemHeight);
    const visibleCount = Math.ceil(height / itemHeight) + 3; // overscan
    const endIndex = Math.min(startIndex + visibleCount, items.length);
    const visibleItems = items.slice(startIndex, endIndex);

    Expected result

    visibleItems contains only the rows currently in view plus a small buffer.

  3. 3

    Render with absolute positioning

    Render the visible items inside a div with position: relative and height = totalHeight. Each item is position: absolute with top = index * itemHeight.

  4. 4

    Add the total height spacer

    The scroll container needs to know the full height to show the scrollbar. Set the inner div height to items.length * itemHeight so the scrollbar reflects all items.

  5. 5

    Test with 10,000 items

    Render a VirtualList with 10,000 items and verify smooth scrolling. Compare with rendering all 10,000 in a normal list — the virtualized version should be instant.

    Code
    const items = Array.from({ length: 10000 }, (_, i) => `Item ${i}`);
    
    function App() {
      return <VirtualList items={items} itemHeight={50} height={500} />;
    }

    Expected result

    10,000 items scroll smoothly; only ~12 DOM nodes exist at any time.

Try it yourself

What you learned

You implemented windowing — the technique behind react-window and react-virtualized. It lets you render lists of any size without performance degradation.

Related Resources

Related Lessons

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to topic