React Cool Virtual

<p align="center"> <a href="https://github.com/wellyshen/react-cool-virtual/blob/master/README.md" title="React Cool Virtual"><img src="https://github.com/wellyshen/react-cool-virtual/blob/master/images/logo.svg" alt="React Cool Virtual"></a> </p> <p align="center">A tiny React hook for rendering large datasets like a breeze.</p> <div align="center">

</div>

Features <!-- omit in toc -->

• ♻️ Renders millions of items with highly performant way, using DOM recycling.
• 🎣 Easy to use, based on React hook.
• 💅🏼 Apply styles without hassle, just few setups.
• 🧱 Supports fixed, variable, dynamic, and real-time heights/widths.
• 🖥 Supports responsive web design (RWD) for better UX.
• 📌 Supports sticky headers for building on-trend lists.
• 🚚 Built-ins load more callback for you to deal with infinite scroll + skeleton screens.
• 🖱 Imperative scroll-to methods for offset, items, and alignment.
• 🛹 Out-of-the-box smooth scrolling and the effect is DIY-able.
• 💬 It's possible to implement stick to bottom and pre-pending items for chat, feeds, etc.
• ⛳ Provides isScrolling indicator to you for UI placeholders or performance optimization.
• 🗄️ Supports server-side rendering (SSR) for a fast FP + FCP and better SEO.
• 📜 Supports TypeScript type definition.
• 🎛 Super flexible API design, built with DX in mind.
• 🦔 Tiny size (~ 3.1kB gzipped). No external dependencies, aside from the react.

Why? <!-- omit in toc -->

When rendering a large set of data (e.g. list, table, etc.) in React, we all face performance/memory troubles. There're some great libraries already available but most of them are component-based solutions that provide well-defineded way of using but increase a lot of bundle size. However, a library comes out as a hook-based solution that is flexible and headless but using and styling it can be verbose (because it's a low-level hook). Furthermore, it lacks many of the useful features.

React Cool Virtual is a tiny React hook that gives you a better DX and modern way for virtualizing a large amount of data without struggle 🤯.

Docs <!-- omit in toc -->

• Getting Started
  • Requirement
  • Installation
  • CDN
  • Basic Usage
• Examples
  • Fixed Size
  • Variable Size
  • Dynamic Size
  • Real-time Resize
  • Responsive Web Design (RWD)
  • Sticky Headers
  • Scroll to Offset / Items
  • Smooth Scrolling
  • Infinite Scroll
  • Pre-pending Items
  • Filtering Items
  • Sticking to Bottom
  • Working with Input Elements
  • Dealing with Dynamic Items
  • Server-side Rendering (SSR)
• API
  • Options
  • Return Values
• Others
  • Performance Optimization
  • How to Share A ref?
  • Layout Items
  • Working in TypeScript
  • ResizeObserver Polyfill

Getting Started

Requirement

To use React Cool Virtual, you must use react@16.8.0 or greater which includes hooks.

Installation

This package is distributed via npm.

$ yarn add react-cool-virtual
# or
$ npm install --save react-cool-virtual

⚠️ This package using ResizeObserver API under the hook. Most modern browsers support it natively, you can also add polyfill for full browser support.

CDN

If you're not using a module bundler or package manager. We also provide a UMD build which is available over the unpkg.com CDN. Simply use a <script> tag to add it after React CDN links as below:

<!-- prettier-ignore-start -->

<script crossorigin src="https://unpkg.com/react/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom/umd/react-dom.production.min.js"></script>
<!-- react-cool-virtual comes here -->
<script crossorigin src="https://unpkg.com/react-cool-virtual/dist/index.umd.production.min.js"></script>

<!-- prettier-ignore-end -->

Once you've added this you will have access to the window.ReactCoolVirtual.useVirtual variable.

Basic Usage

Here's the basic concept of how it rocks:

import useVirtual from "react-cool-virtual";

const List = () => {
  const { outerRef, innerRef, items } = useVirtual({
    itemCount: 10000, // Provide the total number for the list items
    itemSize: 50, // The size of each item (default = 50)
  });

  return (
    <div
      ref={outerRef} // Attach the `outerRef` to the scroll container
      style={{ width: "300px", height: "500px", overflow: "auto" }}
    >
      {/* Attach the `innerRef` to the wrapper of the items */}
      <div ref={innerRef}>
        {items.map(({ index, size }) => (
          // You can set the item's height with the `size` property
          <div key={index} style={{ height: `${size}px` }}>
            ⭐️ {index}
          </div>
        ))}
      </div>
    </div>
  );
};

✨ Pretty easy right? React Cool Virtual is more powerful than you think. Let's explore more use cases through the examples!

Examples

Fixed Size

This example demonstrates how to create a fixed size row. For column or grid, please refer to CodeSandbox.

import useVirtual from "react-cool-virtual";

const List = () => {
  const { outerRef, innerRef, items } = useVirtual({
    itemCount: 1000,
  });

  return (
    <div
      style={{ width: "300px", height: "300px", overflow: "auto" }}
      ref={outerRef}
    >
      <div ref={innerRef}>
        {items.map(({ index, size }) => (
          <div key={index} style={{ height: `${size}px` }}>
            ⭐️ {index}
          </div>
        ))}
      </div>
    </div>
  );
};

Variable Size

This example demonstrates how to create a variable size row. For column or grid, please refer to CodeSandbox.

import useVirtual from "react-cool-virtual";

const List = () => {
  const { outerRef, innerRef, items } = useVirtual({
    itemCount: 1000,
    itemSize: (idx) => (idx % 2 ? 100 : 50),
  });

  return (
    <div
      style={{ width: "300px", height: "300px", overflow: "auto" }}
      ref={outerRef}
    >
      <div ref={innerRef}>
        {items.map(({ index, size }) => (
          <div key={index} style={{ height: `${size}px` }}>
            ⭐️ {index}
          </div>
        ))}
      </div>
    </div>
  );
};

Dynamic Size

This example demonstrates how to create a dynamic (unknown) size row. For column or grid, please refer to CodeSandbox.

import useVirtual from "react-cool-virtual";

const List = () => {
  const { outerRef, innerRef, items } = useVirtual({
    itemCount: 1000,
    itemSize: 75, // The unmeasured item sizes will refer to this value (default = 50)
  });

  return (
    <div
      style={{ width: "300px", height: "300px", overflow: "auto" }}
      ref={outerRef}
    >
      <div ref={innerRef}>
        {items.map((