diff --git a/.changeset/unlucky-cars-yell.md b/.changeset/unlucky-cars-yell.md new file mode 100644 index 000000000..6616d74b1 --- /dev/null +++ b/.changeset/unlucky-cars-yell.md @@ -0,0 +1,5 @@ +--- +"@solid-primitives/virtual": minor +--- + +Add a headless virtual list primitive: `createVirtualList` in #702 diff --git a/packages/virtual/README.md b/packages/virtual/README.md index 23af11d6c..80f3a4c40 100644 --- a/packages/virtual/README.md +++ b/packages/virtual/README.md @@ -9,7 +9,8 @@ [![version](https://img.shields.io/npm/v/@solid-primitives/virtual?style=for-the-badge)](https://www.npmjs.com/package/@solid-primitives/virtual) [![stage](https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-0.json)](https://github.com/solidjs-community/solid-primitives#contribution-process) -A basic [virtualized list](https://www.patterns.dev/vanilla/virtual-lists/) component for improving performance when rendering very large lists +- [`createVirtualList`](#createvirtuallist) - A headless utility function for [virtualized lists](https://www.patterns.dev/vanilla/virtual-lists/) +- [`VirtualList`](#virtuallist) - a basic, unstyled component based on `createVirtualList` ## Installation @@ -23,18 +24,80 @@ pnpm add @solid-primitives/virtual ## How to use it +### `createVirtualList` + +`createVirtualList` is a headless utility for constructing your own virtualized list components with maximum flexibility. + +```tsx +function MyComp(): JSX.Element { + const items = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; + const rootHeight = 20; + const rowHeight = 10; + const overscanCount = 5; + + const [{ containerHeight, viewerTop, visibleItems }, onScroll] = createVirtualList({ + // the list of items - can be a signal + items, + // the height of the root element of the virtualizedList - can be a signal + rootHeight, + // the height of individual rows in the virtualizedList - can be a signal + rowHeight, + // the number of elements to render both before and after the visible section of the list, so passing 5 will render 5 items before the list, and 5 items after. Defaults to 1, cannot be set to zero. This is necessary to hide the blank space around list items when scrolling - can be a signal + overscanCount, + }); + + return ( +