react-list

React List is a lightweight component for rendering large, scrollable collections in React without paying the cost of mounting every item up front. Instead of rendering the full dataset, it tracks the scroll position of its container and incrementally renders only the items near the visible viewport, expanding the rendered window as the user scrolls.

It supports three rendering strategies depending on what’s known about item sizes: simple for straightforward incremental rendering, variable for lists with differently-sized items (with optional size estimation or exact size getters), and uniform for lists where every item shares the same dimensions, which enables the most accurate space calculations and scroll-to-index behavior. The component exposes imperative scrollTo and scrollAround methods and a getVisibleRange accessor, making it a practical building block for feeds, tables, and any UI that needs to display thousands of rows without degrading render performance.

What You Get

• A drop-in <ReactList /> component that renders items incrementally as the user scrolls, avoiding full-list mounts
• Three list types (simple, variable, uniform) to match different item-sizing scenarios, from unknown to uniform heights
• Imperative scrollTo(index) and scrollAround(index) methods for programmatic navigation to a given item
• A getVisibleRange() method to query which item indices are currently visible in the viewport
• Support for both vertical and horizontal (axis: 'x') scrolling lists
• Customizable rendering via itemRenderer and itemsRenderer props, plus a getListStyle override for custom positioning

Common Use Cases

• Rendering long social/activity feeds without mounting thousands of DOM nodes at once
• Displaying large tables or data grids where only visible rows need to be rendered
• Building infinite-scroll UIs that lazily reveal more content as the user scrolls down
• Rendering chat message histories where item heights vary and can’t be known in advance
• Horizontal carousels or filmstrips that virtualize items along the x-axis

Under The Hood

Architecture The entire library is a single class component (src/react-list.js) that keeps its rendered window as { from, size, itemsPerRow, itemSize } in component state, derived on every prop change through a pure constrain() function via getDerivedStateFromProps. Scroll and resize events funnel into an updateFrame dispatcher that branches into one of three strategies (updateSimpleFrame, updateVariableFrame, updateUniformFrame) depending on the type prop, each computing a different from/size window based on measured or cached item offsets. A scrollParentGetter walks up the DOM to auto-detect the nearest scrollable ancestor, and an updateCounter/MAX_SYNC_UPDATES guard exists specifically to detect and halt infinite render loops when item sizing is unstable, printing a documented warning rather than freezing the browser.

Tech Stack React List has a single peer dependency, react (supporting a wide 0.14 || 15 - 19 range), and no runtime dependencies of its own. The build pipeline uses cogs (the author’s own build tool) with Babel presets/plugins to transpile the ES6+ source into a UMD bundle exposing a global alongside CommonJS/AMD support, rather than a mainstream bundler like Rollup or esbuild. Linting runs through eslint-config-coderiety, also maintained by the package author.

Code Quality No test files or CI configuration exist anywhere in the repository — correctness relies entirely on manual verification against the bundled docs/example page and community bug reports. The single source file is dense but readable, with small pure helper functions (constrain, isEqualSubset) isolated from the stateful component logic, and includes defensive numeric guards (e.g. NaN/delta checks around Firefox subpixel sizing quirks). There is no TypeScript and no runtime prop-types validation (removed in an earlier version in favor of relying on documentation), so type errors surface only at runtime.

What Makes It Unique Unlike most list-virtualization libraries that require callers to supply fixed or precomputed item sizes up front, React List’s variable and simple types can operate with limited or no size information, estimating and self-correcting item sizes from the live DOM as items render. Its scroll-parent auto-detection and horizontal/vertical axis support let it virtualize lists inside arbitrary nested scroll containers without extra configuration, and the explicit unstable-state detector is a deliberate, documented safeguard rather than a silent failure mode — a level of defensiveness not universal among comparable libraries.