Quick Features

Row, Column, and Grid virtualization
One single headless hook
Fixed, variable and dynamic measurement modes
Imperative scrollTo control for offset, indices and alignment
Custom scrolling function support (eg. smooth scroll)

Examples

Fixed Rows/Cols/Grid- CodeSandbox - Source
Variable Rows/Cols/Grid- CodeSandbox - Source
Dynamic Rows/Cols/Grid- CodeSandbox - Source
Smooth Scrolling - CodeSandbox - Source
Infinite Scrolling - CodeSandbox - Source

Sponsors

This library is being built and maintained by me, @tannerlinsley and I am always in need of more support to keep projects like this afloat. If you would like to get premium support, add your logo or name on this README, or simply just contribute to my open source Sponsorship goal, visit my Github Sponsors page!

Get Your Logo Here!

Get Your Logo Here!

Get Your Logo Here!

Get Your Name Here!

Get Your Name Here!

Become a Sponsor

Documentation

Installation
Sample
API
- useVirtual
Contributors ✨

Installation

$ npm i --save react-virtual
# or
$ yarn add react-virtual

Why?

React Virtual's most distinguishing feature is that it's just one single custom hook instead of a set of components. In more trendy terms, this means that it is "headless", allowing you to control 100% all of the markup and styles, exactly how you want.

React Virtual supplies you with primitive utilities that allow you to build any range of virtualized experiences. One testament to this is that you can combine 2 instances of useVirtual onto the same markup to achieve a virtualized grid, where with other utilites, you would need to use a dedicated Grid-like component.

Sample

This is just a quick sample of what it looks like to use React Virtual. Please refer to the examples for more usage patterns.

function RowVirtualizerFixed() {
  const parentRef = React.useRef()

  const rowVirtualizer = useVirtual({
    size: 10000,
    parentRef,
    estimateSize: React.useCallback(() => 35, []),
  })

  return (
    <>
      <div
        ref={parentRef}
        className="List"
        style={{
          height: `150px`,
          width: `300px`,
          overflow: 'auto',
        }}
      >
        <div
          className="ListInner"
          style={{
            height: `${rowVirtualizer.totalSize}px`,
            width: '100%',
            position: 'relative',
          }}
        >
          {rowVirtualizer.virtualItems.map(virtualRow => (
            <div
              key={virtualRow.index}
              className={virtualRow.index % 2 ? 'ListItemOdd' : 'ListItemEven'}
              style={{
                position: 'absolute',
                top: 0,
                left: 0,
                width: '100%',
                height: `${virtualRow.size}px`,
                transform: `translateY(${virtualRow.start}px)`,
              }}
            >
              Row {virtualRow.index}
            </div>
          ))}
        </div>
      </div>
    </>
  )
}

API

`useVirtual`

const {
  virtualItems: [
    { index, start, size, end, measureRef },
    /* ... */
  ],
  totalSize,
  scrollToIndex,
  scrollToOffset,
} = useVirtual({
  size,
  parentRef,
  estimateSize,
  overscan,
  horizontal,
  scrollToFn,
  useObserver,
})

Options

Returns

virtualItems: Array<item>
- item: Object
  - index: Integer
    - The index of the item
  - start: Integer
    - The starting measurement of the item
    - Most commonly used for positioning elements
  - size: Integer
    - The static/variable or, if dynamically rendered, the measured size of the item
  - end: Integer
    - The ending measurement of the item
  - measureRef: React.useRef | Function(el: DOMElement) => void 0
    - The ref/function to place on the rendered element to enable dynamic measurement rendering
totalSize: Integer
- The total size of the entire virtualizer
- When using dynamic measurement refs, this number may change as items are measured after they are rendered.
scrollToIndex: Function(index: Integer, { align: String }) => void 0
- Call this function to scroll the top/left of the parentRef element to the start of the item located at the passed index.
- align: 'start' | 'center' | 'end' | 'auto'
  - Defaults to auto
  - start places the item at the top/left of the visible scroll area
  - center places the item in the center of the visible scroll area
  - end places the item at the bottom/right of the visible scroll area
  - auto brings the item into the visible scroll area either at the start or end, depending on which is closer. If the item is already in view, it is placed at the top/left of the visible scroll area.
scrollToOffset: Function(offsetInPixels: Integer, { align: String }) => void 0
- Call this function to scroll the top/left of the parentRef element to the passed pixel offset.
- align: 'start' | 'center' | 'end' | 'auto'
  - Defaults to start
  - start places the offset at the top/left of the visible scroll area
  - center places the offset in the center of the visible scroll area
  - end places the offset at the bottom/right of the visible scroll area
  - auto brings the offset into the visible scroll area either at the start or end, depending on which is closer. If the offset is already in view, it is placed at the top/left of the visible scroll area.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Tanner Linsley}
💻 🤔 💡 🚧 👀

This project follows the all-contributors specification. Contributions of any kind welcome!

License

togoog/react-virtual_scrolling

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages