# virtual-flow

> Virtual scroll library for React applications

Latest version **0.0.4** (published 2023-10-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install virtual-flow
pnpm add virtual-flow
yarn add virtual-flow
bun add virtual-flow
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.4 |
| Published | 2023-10-27 |
| First published | 2023-10-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 36 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | gearonix |
| Keywords | react, virtual, virtual-scroll, scroll |

## Links

- npm: https://www.npmjs.com/package/virtual-flow
- npm.io page: https://npm.io/package/virtual-flow

## Dependencies (1)

- [uuid-v4](https://npm.io/package/uuid-v4.md) ^0.1.0

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.0.4 (latest) — 2023-10-27
- 0.0.3 — 2023-10-26
- 0.0.2 — 2023-10-26

## README

<h1 align="center">
virtual-flow
</h1>
<p align="center">
    An attempt to implement virtual scroll functionality in React for optimizing the handling of large datasets
<p>
<br/>

### Usage

Most of the solutions and implementations were taken from [Ayub Begimkulov](https://github.com/Ayub-Begimkulov/youtube-tutorials/blob/master/virtualization-from-scratch/src/examples/DynamicHeight-improved.tsx).

I just improved and extended it by decomposing, covering it with tests and adding a top-level API for easy use.

---

### Installation

```
$ yarn add virtual-flow
```
Import the `VirtualFlow` component.

```tsx
import { VirtualFlow } from 'virtual-flow'

export const VirtualizedList = () => {
  return (
    <VirtualFlow>
      {items.map((item, idx) => (
        <Item key={idx}>
          {item.text}
        </Item>
      ))}
    </VirtualFlow>
  )
}
```

If you are using a component, you should use [forwardRef](https://react.dev/reference/react/forwardRef)
to pass the ref to the regular element.

```tsx
export const Item = forwardRef<
  HTMLDivElement,
  WithChildren<ItemProps>
>(({ children }, ref) => {
  return (
    <div ref={ref}>
      {children}
    </div>
  )
})
```

The library can work with dynamic heights of elements, implements caching of element heights,
reacts to changes in the length of elements (using [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)) and also uses techniques such as scroll correction.


<img src="https://github.com/Gearonix/virtual-flow/blob/media/showcase.gif" width="70%" height="50%" />

### Run Example

```sh
$ nx serve dev
```

### Run tests with Vitest
```sh
$ nx test
```

## Build library

```sh
$ nx build
```

---

## Usage API

| Property                                |                   Type                   | Description                           |
| --------------------------------------- | :--------------------------------------: | :--------------------------------------- |
| onScroll                                |            (scrollTop: number) => void           | Callback, which will be called at the time of scrolling               |
| estimateHeight                                   |                  number                  | Approximate length of the element, it is highly recommended to set|
| scrollingDelay                                  |                  number                  | Delay at which callback `onScroll` will be called |
| overscan                                |           number           | Number of elements that need to be rendered additionally |
| itemHeight                |           (height: number) => number            | Constant height of the element. Use only if you have elements of the same length |

---
_Source: https://npm.io/package/virtual-flow · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._