virtual-scroller 1.15.0 → 1.15.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 <!-- `virtual-scroller`: in `.updateItems()` handle a case when `items.length` is the same, in which case find different items and if those items are rendered then maybe update them on screen and update their height, if the items are past rendered then maybe just discard all item heights past rendered, if the items are before rendered then maybe ignore and it will jump on scroll up which is kinda acceptable. -->
 
+1.15.1 / 30.11.2025
+===================
+
+* Added `useVirtualScroller()` hook that is exported from `virtual-scroller/react` subpackage.
+* Un-deprecated `tbody: boolean` property because it's used in the new hook.
+
 1.15.0 / 30.11.2025
 ===================
 

package/README.md

@@ -29,6 +29,8 @@ A universal open-source implementation of Twitter's [`VirtualScroller`](https://
 * [Table in a scrollable container](https://catamphetamine.gitlab.io/virtual-scroller/index-react-tbody-scrollableContainer.html)
 * [Grid](https://catamphetamine.gitlab.io/virtual-scroller/index-react-grid.html)
 * [Paginated Grid](https://catamphetamine.gitlab.io/virtual-scroller/index-react-grid.html?pagination=✓)
+* [List (using hook)](https://catamphetamine.gitlab.io/virtual-scroller/index-react-hook.html)
+* [Paginated List (using hook)](https://catamphetamine.gitlab.io/virtual-scroller/index-react-hook.html?pagination=✓)
 
 ## Rationale
 
@@ -172,6 +174,18 @@ function App() {
 
 <!-- Note: When passing any core `VirtualScroller` class options, only the initial values of those options will be applied, and any updates to those options will be ignored. That's because those options are only passed to the `VirtualScroller` base class constructor at initialization time. That means that none of those options should depend on any variable state or props. For example, if `getColumnsCount()` parameter was defined as `() => props.columnsCount`, then, if the `columnsCount` property changes, the underlying `VirtualScroller` instance won't see that change. -->
 
+<!-- I guess that `style` property should be deprecated because it could potentially be dangerous
+     due to potential conflicts with `VirtualScroller` styles. It currently isn't present anyway. -->
+<!-- * `style: object` — Custom CSS style, except for `padding-top` or `padding-bottom`. -->
+
+<!-- I guess that `className` property should be deprecated because it could potentially be dangerous
+     due to potential conflicts with `VirtualScroller` styles. -->
+<!-- * `className: string` — Custom CSS class name. -->
+
+* `tbody: boolean` — When the list items container element is going to be a `<tbody/>`, it will have to use a special workaround in order for the `<VirtualScroller/>` to work correctly. To enable this special workaround, a developer could pass a `tbody: true` property. Otherwise, `<VirtualScroller/>` will only enable it when `itemsContainerComponent === "tbody"`.
+  <!-- * There's no longer such option in the ["core"](#core) component because it's autodetected there. The reason why it can't always be autodetected in React is because of server-side rendering when there's no items container DOM element whose tag name could be examined to detect the use of a `<tbody/>` tag as an items container. -->
+  * Only the initial value of this property is used, and any changes to it will be ignored.
+
 * `getColumnsCount(): number` — Returns the count of the columns.
   * This is simply a proxy for the ["core"](#core) component's `getColumnsCount` [option](#options).
   * Only the initial value of this property is used, and any changes to it will be ignored.
@@ -277,14 +291,6 @@ function ListContainer() {
 }
 ```
 
-<!--
-(this property has been ignored for a long time and was eventually removed)
-
-* `tbody: boolean` — When the container for the list items is going to be a `<tbody/>`, a developer must pass a `tbody: true` property in order for the `<VirtualScroller/>` to work correctly.
-  * This is simply a proxy for the ["core"](#core) component's `tbody` option.
-  * Only the initial value of this property is used, and any changes to it will be ignored.
--->
-
 * `itemsContainerComponentRef: object` — Could be used to get access to the `itemsContainerComponent` instance.
   * For example, if `itemsContainerComponent` is `"ul"` then `itemsContainerComponentRef.current` will be set to the `<ul/>` `Element`.
 
@@ -475,6 +481,90 @@ By default, on server side, it will just render the first item, as if the list o
 To fix that, a developer should specify certain properties — `getEstimatedVisibleItemRowsCount(): number` and `getEstimatedItemHeight(): number` and `getEstimatedInterItemVerticalSpacing(): number` — so that it could calculate how many items it should render and how much space it should leave for scrolling. For more technical details, see the description of these parameters in the ["core"](#core) component's [options](#options).
 </details>
 
+######
+
+<details>
+<summary>Alternatively, instead of using <code>&lt;VirtualScroller/&gt;</code> component, one could use <code>useVirtualScroller()</code> hook</summary>
+
+######
+
+```js
+import React from 'react'
+import { useVirtualScroller } from 'virtual-scroller/react'
+
+function List(props) {
+  const {
+    // "Core" component `state`.
+    // See "State" section of the readme for more info.
+    state: {
+      items,
+      itemStates,
+      firstShownItemIndex,
+      lastShownItemIndex
+    },
+    // CSS style object.
+    style,
+    // CSS class name.
+    className,
+    // This `ref` must be passed to the items container component.
+    itemsContainerRef,
+    // One could use this `virtualScroller` object to call any of its public methods.
+    // Except for `virtualScroller.getState()` — use the returned `state` property instead.
+    virtualScroller
+  } = useVirtualScroller({
+    // The properties of `useVirtualScroller()` hook are the same as
+    // the properties of `<VirtualScroller/>` component.
+    //
+    // Additional properties:
+    // * `style`
+    // * `className`
+    //
+    // Excluded properties:
+    // * `itemComponent`
+    // * `itemComponentProps`
+    // * `itemsContainerComponent`
+    // * `itemsContainerComponentProps`
+    //
+    items: props.items
+  })
+
+  return (
+    <div ref={itemsContainerRef} style={style} className={className}>
+      {items.map((item, i) => {
+        if (i >= firstShownItemIndex && i <= lastShownItemIndex) {
+          return (
+            <ListItem
+              key={item.id}
+              item={item}
+              state={itemStates && itemStates[i]}
+            />
+          )
+        }
+        return null
+      })}
+    </div>
+  )
+}
+
+function ListItem({ item, state }) {
+  const { username, date, text } = item
+  return (
+    <article>
+      <a href={`/users/${username}`}>
+        @{username}
+      </a>
+      <time dateTime={date.toISOString()}>
+        {date.toString()}
+      </time>
+      <p>
+        {text}
+      </p>
+    </article>
+  )
+}
+```
+</details>
+
 ## DOM
 
 `virtual-scroller/dom` exports a `VirtualScroller` class that implements a "virtual scroller" in a standard [Document Object Model](https://en.wikipedia.org/wiki/Document_Object_Model) environment such as a web browser.

package/bundle/index-dom-bypass.html

@@ -72,6 +72,7 @@
 				const { toIndex } = getState()
 				fromIndex = Math.max(fromIndex - BATCH_SIZE, 0)
 				setState({
+					...getState(),
 					fromIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
@@ -82,6 +83,7 @@
 				let { toIndex } = getState()
 				toIndex = Math.min(toIndex + BATCH_SIZE, items.length - 1)
 				setState({
+					...getState(),
 					toIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
@@ -159,10 +161,7 @@
 
 				setState = (newState) => {
 					const prevState = this.state
-					this.state = {
-						...this.state,
-						...newState
-					}
+					this.state = newState
 					this.onStateChange(this.state, prevState)
 				}
 

package/bundle/index-dom-grid.html

@@ -78,6 +78,7 @@
 				const { toIndex } = getState()
 				fromIndex = Math.max(fromIndex - BATCH_SIZE, 0)
 				setState({
+					...getState(),
 					fromIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
@@ -88,6 +89,7 @@
 				let { toIndex } = getState()
 				toIndex = Math.min(toIndex + BATCH_SIZE, items.length - 1)
 				setState({
+					...getState(),
 					toIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
@@ -165,10 +167,7 @@
 
 				setState = (newState) => {
 					const prevState = this.state
-					this.state = {
-						...this.state,
-						...newState
-					}
+					this.state = newState
 					this.onStateChange(this.state, prevState)
 				}
 

package/bundle/index-dom-scrollableContainer.html

@@ -85,6 +85,7 @@
 				const { toIndex } = getState()
 				fromIndex = Math.max(fromIndex - BATCH_SIZE, 0)
 				setState({
+					...getState(),
 					fromIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
@@ -95,6 +96,7 @@
 				let { toIndex } = getState()
 				toIndex = Math.min(toIndex + BATCH_SIZE, items.length - 1)
 				setState({
+					...getState(),
 					toIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
@@ -176,10 +178,7 @@
 
 				setState = (newState) => {
 					const prevState = this.state
-					this.state = {
-						...this.state,
-						...newState
-					}
+					this.state = newState
 					this.onStateChange(this.state, prevState)
 				}
 

package/bundle/index-dom.html

@@ -72,6 +72,7 @@
 				const { toIndex } = getState()
 				fromIndex = Math.max(fromIndex - BATCH_SIZE, 0)
 				setState({
+					...getState(),
 					fromIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
@@ -82,6 +83,7 @@
 				let { toIndex } = getState()
 				toIndex = Math.min(toIndex + BATCH_SIZE, items.length - 1)
 				setState({
+					...getState(),
 					toIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
@@ -159,10 +161,7 @@
 
 				setState = (newState) => {
 					const prevState = this.state
-					this.state = {
-						...this.state,
-						...newState
-					}
+					this.state = newState
 					this.onStateChange(this.state, prevState)
 				}
 

package/bundle/index-react-bypass.html

@@ -64,6 +64,7 @@
 				const { toIndex } = getState()
 				fromIndex = Math.max(fromIndex - BATCH_SIZE, 0)
 				setState({
+					...getState(),
 					fromIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
@@ -74,64 +75,59 @@
 				let { toIndex } = getState()
 				toIndex = Math.min(toIndex + BATCH_SIZE, items.length - 1)
 				setState({
+					...getState(),
 					toIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
 			}
 
-			class VirtualScrollerDemo extends React.Component {
-				constructor(props) {
-					super(props)
+			function VirtualScrollerDemo() {
+				const [state, setState] = React.useState(getInitialState(ITEMS))
 
-					this.state = getInitialState(ITEMS)
-				}
-
-				getState = () => this.state
+				const getState = () => state
 
-				onShowPrevious = () => {
-					onShowPrevious(ITEMS, this.getState, this.setState.bind(this))
+				const onShowPrevious_ = () => {
+					onShowPrevious(ITEMS, getState, setState)
 				}
 
-				onShowNext = () => {
-					onShowNext(ITEMS, this.getState, this.setState.bind(this))
+				const onShowNext_ = () => {
+					onShowNext(ITEMS, getState, setState)
 				}
 
-				render() {
-					const {
-						fromIndex,
-						toIndex,
-						items
-					} = this.state
-
-					return (
-						<React.Fragment>
-							{window.PAGINATION && fromIndex > 0 &&
-								<button
-									type="button"
-									onClick={this.onShowPrevious}
-									className="load-items-button">
-									Show previous
-								</button>
-							}
-							<VirtualScroller
-								bypass
-								id="list"
-								items={items}
-								itemComponent={Item}
-								preserveScrollPositionOnPrependItems
-								getColumnsCount={getColumnsCount}
-							/>
-							{window.PAGINATION && toIndex < ITEMS.length - 1 &&
-								<button
-									type="button"
-									onClick={this.onShowNext}
-									className="load-items-button">
-									Show next
-								</button>
-							}
-						</React.Fragment>
-					)
-				}
+				const {
+					fromIndex,
+					toIndex,
+					items
+				} = state
+
+				return (
+					<React.Fragment>
+						{window.PAGINATION && fromIndex > 0 &&
+							<button
+								type="button"
+								onClick={onShowPrevious_}
+								className="load-items-button">
+								Show previous
+							</button>
+						}
+						<VirtualScroller
+							bypass
+							id="list"
+							items={items}
+							itemComponent={Item}
+							preserveScrollPositionOnPrependItems
+							getColumnsCount={getColumnsCount}
+						/>
+						{window.PAGINATION && toIndex < ITEMS.length - 1 &&
+							<button
+								type="button"
+								onClick={onShowNext_}
+								className="load-items-button">
+								Show next
+							</button>
+						}
+					</React.Fragment>
+				)
 			}
 
 			const item = PropTypes.shape({
@@ -168,21 +164,19 @@
 				children: item.isRequired
 			}
 
-			class Demo extends React.Component {
-				render() {
-					return (
-						<section className="container">
-							<h1>
-								<TwitterLogo/>
-								Latest Tweets on #politics
-							</h1>
-							<VirtualScrollerDemo/>
-							<footer>
-								© Twitter Inc., 2019
-							</footer>
-						</section>
-					)
-				}
+			function Demo() {
+				return (
+					<section className="container">
+						<h1>
+							<TwitterLogo/>
+							Latest Tweets on #politics
+						</h1>
+						<VirtualScrollerDemo/>
+						<footer>
+							© Twitter Inc., 2019
+						</footer>
+					</section>
+				)
 			}
 
 			function TwitterLogo() {

package/bundle/index-react-grid.html

@@ -68,6 +68,7 @@
 				const { toIndex } = getState()
 				fromIndex = Math.max(fromIndex - BATCH_SIZE, 0)
 				setState({
+					...getState(),
 					fromIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
@@ -78,63 +79,58 @@
 				let { toIndex } = getState()
 				toIndex = Math.min(toIndex + BATCH_SIZE, items.length - 1)
 				setState({
+					...getState(),
 					toIndex,
 					items: items.slice(fromIndex, toIndex + 1)
 				})
 			}
 
-			class VirtualScrollerDemo extends React.Component {
-				constructor(props) {
-					super(props)
+			function VirtualScrollerDemo() {
+				const [state, setState] = React.useState(getInitialState(ITEMS))
 
-					this.state = getInitialState(ITEMS)
-				}
-
-				getState = () => this.state
+				const getState = () => state
 
-				onShowPrevious = () => {
-					onShowPrevious(ITEMS, this.getState, this.setState.bind(this))
+				const onShowPrevious_ = () => {
+					onShowPrevious(ITEMS, getState, setState)
 				}
 
-				onShowNext = () => {
-					onShowNext(ITEMS, this.getState, this.setState.bind(this))
+				const onShowNext_ = () => {
+					onShowNext(ITEMS, getState, setState)
 				}
 
-				render() {
-					const {
-						fromIndex,
-						toIndex,
-						items
-					} = this.state
-
-					return (
-						<React.Fragment>
-							{window.PAGINATION && fromIndex > 0 &&
-								<button
-									type="button"
-									onClick={this.onShowPrevious}
-									className="load-items-button">
-									Show previous
-								</button>
-							}
-							<VirtualScroller
-								id="list"
-								items={items}
-								itemComponent={Item}
-								preserveScrollPositionOnPrependItems
-								getColumnsCount={getColumnsCount}
-							/>
-							{window.PAGINATION && toIndex < ITEMS.length - 1 &&
-								<button
-									type="button"
-									onClick={this.onShowNext}
-									className="load-items-button">
-									Show next
-								</button>
-							}
-						</React.Fragment>
-					)
-				}
+				const {
+					fromIndex,
+					toIndex,
+					items
+				} = state
+
+				return (
+					<React.Fragment>
+						{window.PAGINATION && fromIndex > 0 &&
+							<button
+								type="button"
+								onClick={onShowPrevious_}
+								className="load-items-button">
+								Show previous
+							</button>
+						}
+						<VirtualScroller
+							id="list"
+							items={items}
+							itemComponent={Item}
+							preserveScrollPositionOnPrependItems
+							getColumnsCount={getColumnsCount}
+						/>
+						{window.PAGINATION && toIndex < ITEMS.length - 1 &&
+							<button
+								type="button"
+								onClick={onShowNext_}
+								className="load-items-button">
+								Show next
+							</button>
+						}
+					</React.Fragment>
+				)
 			}
 
 			const item = PropTypes.shape({
@@ -171,21 +167,19 @@
 				children: item.isRequired
 			}
 
-			class Demo extends React.Component {
-				render() {
-					return (
-						<section className="container">
-							<h1>
-								<TwitterLogo/>
-								Latest Tweets on #politics
-							</h1>
-							<VirtualScrollerDemo/>
-							<footer>
-								© Twitter Inc., 2019
-							</footer>
-						</section>
-					)
-				}
+			function Demo() {
+				return (
+					<section className="container">
+						<h1>
+							<TwitterLogo/>
+							Latest Tweets on #politics
+						</h1>
+						<VirtualScrollerDemo/>
+						<footer>
+							© Twitter Inc., 2019
+						</footer>
+					</section>
+				)
 			}
 
 			function TwitterLogo() {