virtual-scroller 1.14.0 → 1.15.0

package/source/Layout.js

@@ -1,13 +1,14 @@
 import log, { warn } from './utility/debug.js'
 import ScrollableContainerNotReadyError from './ScrollableContainerNotReadyError.js'
+import { DEFAULT_VISIBLE_ITEM_ROWS_COUNT } from './Layout.defaults.js'
 
 export default class Layout {
 	constructor({
 		isInBypassMode,
-		getInitialEstimatedItemHeight,
-		getInitialEstimatedVisibleItemRowsCount,
+		getEstimatedVisibleItemRowsCountForInitialRender,
 		measureItemsBatchSize,
 		getPrerenderMargin,
+		getPrerenderMarginRatio,
 		getVerticalSpacing,
 		getVerticalSpacingBeforeResize,
 		getColumnsCount,
@@ -20,10 +21,10 @@ export default class Layout {
 		getPreviouslyCalculatedLayout
 	}) {
 		this.isInBypassMode = isInBypassMode
-		this.getInitialEstimatedItemHeight = getInitialEstimatedItemHeight
-		this.getInitialEstimatedVisibleItemRowsCount = getInitialEstimatedVisibleItemRowsCount
+		this.getEstimatedVisibleItemRowsCountForInitialRender = getEstimatedVisibleItemRowsCountForInitialRender
 		this.measureItemsBatchSize = measureItemsBatchSize
 		this.getPrerenderMargin = getPrerenderMargin
+		this.getPrerenderMarginRatio = getPrerenderMarginRatio
 		this.getVerticalSpacing = getVerticalSpacing
 		this.getVerticalSpacingBeforeResize = getVerticalSpacingBeforeResize
 		this.getColumnsCount = getColumnsCount
@@ -69,6 +70,10 @@ export default class Layout {
 	}) {
 		let firstShownItemIndex
 		let lastShownItemIndex
+
+		let beforeItemsHeight = 0
+		let afterItemsHeight = 0
+
 		// If there're no items then `firstShownItemIndex` stays `undefined`.
 		if (itemsCount > 0) {
 			const getLastShownItemIndex = () => {
@@ -78,18 +83,30 @@ export default class Layout {
 					firstShownItemIndex
 				})
 			}
+
 			firstShownItemIndex = 0
+
 			lastShownItemIndex = beforeStart
 				? this.getInitialLayoutValueWithFallback(
 					'lastShownItemIndex',
 					getLastShownItemIndex,
-					0
+					firstShownItemIndex
 				)
 				: getLastShownItemIndex()
+
+			const averageItemHeight = this.getAverageItemHeight()
+			const verticalSpacing = this.getVerticalSpacing()
+
+			const beforeItemsCount = firstShownItemIndex
+			const afterItemsCount = itemsCount - (lastShownItemIndex + 1)
+
+			beforeItemsHeight = Math.ceil(beforeItemsCount / columnsCount) * (verticalSpacing + averageItemHeight)
+			afterItemsHeight = Math.ceil(afterItemsCount / columnsCount) * (verticalSpacing + averageItemHeight)
 		}
+
 		return {
-			beforeItemsHeight: 0,
-			afterItemsHeight: 0,
+			beforeItemsHeight,
+			afterItemsHeight,
 			firstShownItemIndex,
 			lastShownItemIndex
 		}
@@ -103,54 +120,47 @@ export default class Layout {
 		if (this.isInBypassMode()) {
 			return itemsCount - 1
 		}
-		// On server side, at initialization time,
-		// `scrollableContainer` is `undefined`,
-		// so default to `1` estimated rows count.
-		let estimatedRowsCount = 1
-		if (this.getMaxVisibleAreaHeight()) {
-			estimatedRowsCount = this.getEstimatedRowsCountForHeight(this.getMaxVisibleAreaHeight() + this.getPrerenderMargin())
-		} else if (this.getInitialEstimatedVisibleItemRowsCount) {
-			estimatedRowsCount = this.getInitialEstimatedVisibleItemRowsCount()
-			if (isNaN(estimatedRowsCount)) {
-				throw new Error('[virtual-scroller] `getEstimatedVisibleItemRowsCount()` must return a number')
-			}
-		}
 		return Math.min(
-			firstShownItemIndex + (estimatedRowsCount * columnsCount - 1),
+			firstShownItemIndex + (this.getInitialRenderedRowsCount() * columnsCount - 1),
 			itemsCount - 1
 		)
 	}
 
-	getEstimatedRowsCountForHeight(height) {
-		const estimatedItemHeight = this.getEstimatedItemHeight()
-		const verticalSpacing = this.getVerticalSpacing()
-		if (estimatedItemHeight) {
-			return Math.ceil((height + verticalSpacing) / (estimatedItemHeight + verticalSpacing))
-		} else {
-			// If no items have been rendered yet, and no `estimatedItemHeight` option
-			// has been passed, then default to `1` estimated rows count in any `height`.
-			return 1
+	getInitialRenderedRowsCount() {
+		const estimatedVisibleItemRowsCount = this.getEstimatedVisibleItemRowsCount()
+		if (typeof estimatedVisibleItemRowsCount === 'number') {
+			return Math.ceil(estimatedVisibleItemRowsCount * (1 + this.getPrerenderMarginRatio()))
 		}
+		// `DEFAULT_VISIBLE_ITEM_ROWS_COUNT` will be used in server-side render
+		// unless `getEstimatedVisibleItemRowsCount()` parameter is specified.
+		return DEFAULT_VISIBLE_ITEM_ROWS_COUNT
 	}
 
-	/**
-	 * Returns estimated list item height.
-	 * (depends on which items have been previously rendered and measured).
-	 * @return {number}
-	 */
-	getEstimatedItemHeight() {
-		const averageItemHeight = this.getAverageItemHeight()
-		if (averageItemHeight) {
-			return averageItemHeight
+	getEstimatedVisibleItemRowsCount() {
+		const maxVisibleAreaHeight = this.getMaxVisibleAreaHeight()
+		if (typeof maxVisibleAreaHeight === 'number') {
+			const estimatedRowsCount = this.getEstimatedRowsCountForHeight(maxVisibleAreaHeight)
+			if (typeof estimatedRowsCount === 'number') {
+				return estimatedRowsCount
+			}
 		}
-		if (this.getInitialEstimatedItemHeight) {
-			const estimatedItemHeight = this.getInitialEstimatedItemHeight()
-			if (isNaN(estimatedItemHeight)) {
-				throw new Error('[virtual-scroller] `getInitialEstimatedItemHeight()` must return a number')
+		if (this.getEstimatedVisibleItemRowsCountForInitialRender) {
+			const estimatedRowsCount = this.getEstimatedVisibleItemRowsCountForInitialRender()
+			if (typeof estimatedRowsCount === 'number') {
+				return estimatedRowsCount
 			}
-			return estimatedItemHeight
+			throw new Error('[virtual-scroller] `getEstimatedVisibleItemRowsCount()` must return a number')
+		}
+	}
+
+	getEstimatedRowsCountForHeight(height) {
+		const averageItemHeight = this.getAverageItemHeight()
+		const verticalSpacing = this.getVerticalSpacing()
+		// `estimatedItemHeight` will most likely be `0` if it hasn't been specified explicitly.
+		// In that case, it can't divide by `0`.
+		if (averageItemHeight + verticalSpacing > 0) {
+			return Math.ceil((height + verticalSpacing) / (averageItemHeight + verticalSpacing))
 		}
-		return 0
 	}
 
 	getLayoutUpdateForItemsDiff({
@@ -328,8 +338,17 @@ export default class Layout {
 
 		const columnsCount = this.getColumnsCount()
 
+		const getNonMeasuredItemRowsCount = () => {
+			const estimatedRowsCount = this.getEstimatedRowsCountForHeight(nonMeasuredAreaHeight)
+			if (typeof estimatedRowsCount === 'number') {
+				return estimatedRowsCount
+			}
+			// Render all available item rows as a sensible fallback behavior.
+			return Math.ceil(itemsCount / columnsCount)
+		}
+
 		const itemsCountToRenderForMeasurement = Math.min(
-			this.getEstimatedRowsCountForHeight(nonMeasuredAreaHeight) * columnsCount,
+			getNonMeasuredItemRowsCount() * columnsCount,
 			this.measureItemsBatchSize || Infinity,
 		)
 
@@ -434,15 +453,12 @@ export default class Layout {
 		// then `shownItemsHeight` would also have to be returned from this function:
 		// the total height of all shown items including vertical spacing between them.
 		//
-		// If "previously calculated layout" would be used then it would first find
-		// `firstShownItemIndex` and then find `lastShownItemIndex` as part of two
+		// If "previously calculated layout" would be used then it would first calculate
+		// `firstShownItemIndex` and then calculate `lastShownItemIndex` as part of two
 		// separate calls of this function, each with or without `backwards` flag,
 		// depending on whether `visibleAreaInsideTheList.top` and `visibleAreaInsideTheList.top`
 		// have shifted up or down.
 
-		let firstShownItemIndex
-		let lastShownItemIndex
-
 		// It's not always required to pass `beforeItemsHeight` parameter:
 		// when `fromIndex` is `0`, it's also assumed to be `0`.
 		if (fromIndex === 0) {
@@ -678,8 +694,6 @@ export default class Layout {
 		const verticalSpacing = beforeResize ? this.getVerticalSpacingBeforeResize() : this.getVerticalSpacing()
 
 		while (i < beforeItemsCount) {
-			const currentRowFirstItemIndex = i
-
 			let rowHeight = 0
 			let columnIndex = 0
 			// Not checking for `itemsCount` overflow here because `i = beforeItemsCount`
@@ -734,7 +748,6 @@ export default class Layout {
 		// Which becomes negligible in my project's use case (a couple thousands items max).
 
 		const columnsCount = this.getColumnsCount()
-		const lastShownRowIndex = Math.floor(lastShownItemIndex / columnsCount)
 
 		let afterItemsHeight = 0
 

package/source/Layout.test.js

@@ -158,9 +158,11 @@ describe('Layout', function() {
 
 		let shouldResetGridLayout
 
+		// Don't `throw` `VirtualScroller` errors but rather collect them in an array.
 		const errors = []
-
-		global.VirtualScrollerCatchError = (error) => errors.push(error)
+		global.VirtualScrollerCatchError = (error) => {
+			errors.push(error)
+		}
 
 		layout.getLayoutUpdateForItemsDiff(
 			{
@@ -185,7 +187,10 @@ describe('Layout', function() {
 			afterItemsHeight: 5 * (ITEM_HEIGHT + VERTICAL_SPACING)
 		})
 
+		// Stop collecting `VirtualScroller` errors in the `errors` array.
+		// Use the default behavior of just `throw`-ing such errors.
 		global.VirtualScrollerCatchError = undefined
+		// Verify the errors that have been `throw`-n.
 		errors.length.should.equal(2)
 		errors[0].message.should.equal('[virtual-scroller] ~ Prepended items count 5 is not divisible by Columns Count 4 ~')
 		errors[1].message.should.equal('[virtual-scroller] Layout reset required')

package/source/VirtualScroller.constructor.js

@@ -1,6 +1,7 @@
 import DOMEngine from './DOM/Engine.js'
 
 import Layout, { LAYOUT_REASON } from './Layout.js'
+import { DEFAULT_ITEM_HEIGHT } from './Layout.defaults.js'
 import ScrollableContainerResizeHandler from './ScrollableContainerResizeHandler.js'
 import BeforeResize from './BeforeResize.js'
 import Scroll from './Scroll.js'
@@ -45,6 +46,7 @@ export default function VirtualScrollerConstructor(
 		// `estimatedItemHeight` is deprecated, use `getEstimatedItemHeight()` instead.
 		estimatedItemHeight,
 		getEstimatedVisibleItemRowsCount,
+		getEstimatedInterItemVerticalSpacing,
 		onItemInitialRender,
 		// `onItemFirstRender(i)` is deprecated, use `onItemInitialRender(item)` instead.
 		onItemFirstRender,
@@ -167,7 +169,7 @@ export default function VirtualScrollerConstructor(
 
 	createStateHelpers.call(this, { state, getInitialItemState, onStateChange, render, items })
 
-	createVerticalSpacingHelpers.call(this)
+	createVerticalSpacingHelpers.call(this, { getEstimatedInterItemVerticalSpacing })
 	createColumnsHelpers.call(this, { getColumnsCount })
 
 	createLayoutHelpers.call(this)
@@ -236,12 +238,33 @@ function createHelpers({
 		setItemHeight: (i, height) => this.getState().itemHeights[i] = height
 	})
 
+	this.getAverageItemHeight = () => {
+		const averageItemHeight = this.itemHeights.getAverageItemHeight()
+		if (typeof averageItemHeight === 'number') {
+			return averageItemHeight
+		}
+		return this.getEstimatedItemHeight()
+	}
+
+	this.getEstimatedItemHeight = () => {
+		if (getEstimatedItemHeight) {
+			const estimatedItemHeight = getEstimatedItemHeight()
+			if (typeof estimatedItemHeight === 'number') {
+				return estimatedItemHeight
+			}
+			throw new Error('[virtual-scroller] `getEstimatedItemHeight()` must return a number')
+		}
+		// `DEFAULT_ITEM_HEIGHT` will be used in server-side render
+		// unless `getEstimatedItemHeight()` parameter is specified.
+		return DEFAULT_ITEM_HEIGHT
+	}
+
 	this.layout = new Layout({
 		isInBypassMode: this.isInBypassMode,
-		getInitialEstimatedItemHeight: getEstimatedItemHeight,
-		getInitialEstimatedVisibleItemRowsCount: getEstimatedVisibleItemRowsCount,
+		getEstimatedVisibleItemRowsCountForInitialRender: getEstimatedVisibleItemRowsCount,
 		measureItemsBatchSize,
 		getPrerenderMargin: () => this.getPrerenderMargin(),
+		getPrerenderMarginRatio: () => this.getPrerenderMarginRatio(),
 		getVerticalSpacing: () => this.getVerticalSpacing(),
 		getVerticalSpacingBeforeResize: () => this.getVerticalSpacingBeforeResize(),
 		getColumnsCount: () => this.getColumnsCount(),
@@ -249,7 +272,7 @@ function createHelpers({
 		getItemHeight: (i) => this.getState().itemHeights[i],
 		getItemHeightBeforeResize: (i) => this.getState().beforeResize && this.getState().beforeResize.itemHeights[i],
 		getBeforeResizeItemsCount: () => this.getState().beforeResize ? this.getState().beforeResize.itemHeights.length : 0,
-		getAverageItemHeight: () => this.itemHeights.getAverage(),
+		getAverageItemHeight: () => this.getAverageItemHeight(),
 		// `this.scrollableContainer` is gonna be `undefined` during server-side rendering.
 		// https://gitlab.com/catamphetamine/virtual-scroller/-/issues/30
 		getMaxVisibleAreaHeight: () => this.scrollableContainer && this.scrollableContainer.getHeight(),

package/source/VirtualScroller.items.js

@@ -1,4 +1,4 @@
-import log, { isDebug } from './utility/debug.js'
+import log, { reportError } from './utility/debug.js'
 import getItemsDiff from './getItemsDiff.js'
 import fillArray from './utility/fillArray.js'
 
@@ -7,6 +7,49 @@ export default function() {
 		return this.getState().items.length
 	}
 
+	this._getItemIndexByItemOrIndex = (itemOrIndex) => {
+		const item = itemOrIndex
+		const { items } = this.getState()
+		// Find the `item`'s index in the `items` array.
+		//
+		// Performance notes:
+		// Doing an `.indexOf()` operation on a very large array could be inefficient
+		// because it would have to check every element of the array.
+		// In case of any hypothetical performance-related issues,
+		// the code could use a `new Map()` as an "index" for finding individual items.
+		const i = items.indexOf(item)
+		// validate that the `item` exists in the `items` array.
+		if (i >= 0) {
+			return i
+		}
+
+		// Legacy behavior: some functions used to accept an `i: number` item index as an argument.
+		// Later the argument was changed to `item: Item`.
+		//
+		// The old way of passing an `i: number` argument would only result in weird application behavior
+		// when all of the below circumstances are true, which is assumed extremely unlikely:
+		//
+		// BOTH use a previous version of `virtual-scroller` (ones before December 2025, with downloads count that is not very high)
+		// AND to be used with an `items` array of type `number[]`
+		// AND to use any of the "advanced" functions:
+    // * `setItemState(i, newState)`
+    // * `onItemHeightDidChange(i)`
+    // * `getItemScrollPosition(i)`
+		//
+		// The code below handles the legacy compatibility aspect of the old type of argument
+		// except maybe for those "extremely unlikely" cases in which the app is still unlikely to crash.
+		//
+		if (typeof itemOrIndex === 'number') {
+			const i = itemOrIndex
+			// Validate the item index argument.
+			if (i >= 0 && i < items.length) {
+				return i
+			}
+		}
+
+		reportError(`Item not found: ${JSON.stringify(item)}`)
+	}
+
 	/**
 	 * Updates `items`. For example, can prepend or append new items to the list.
 	 * @param  {any[]} newItems
@@ -81,7 +124,9 @@ export default function() {
 			if (prependedItemsCount > 0) {
 				log('Prepend', prependedItemsCount, 'items')
 
-				itemHeights = new Array(prependedItemsCount).concat(itemHeights)
+				itemHeights = new Array(prependedItemsCount)
+					.concat(itemHeights)
+
 				itemStates = fillArray(
 					new Array(prependedItemsCount),
 					(i) => this.getInitialItemState(newItems[i])

package/source/VirtualScroller.js

@@ -206,10 +206,19 @@ export default class VirtualScroller {
 
 	/**
 	 * Returns the items's top offset relative to the scrollable container's top edge.
-	 * @param {number} i — Item index
+	 * @param {any} item — Item
 	 * @return {[number]} Returns the item's scroll Y position. Returns `undefined` if any of the previous items haven't been rendered yet.
 	 */
-	getItemScrollPosition(i) {
+	getItemScrollPosition(itemOrIndex) {
+		// Item index.
+		const i = this._getItemIndexByItemOrIndex(itemOrIndex)
+
+		// If the item wasn't found, the error was already reported,
+		// so just return some "sensible" default value.
+		if (i === undefined) {
+			return
+		}
+
 		const itemTopOffsetInList = this.layout.getItemTopOffset(i)
 		if (itemTopOffsetInList === undefined) {
 			return
@@ -221,28 +230,28 @@ export default class VirtualScroller {
 	 * @deprecated
 	 * `.onItemHeightChange()` has been renamed to `.onItemHeightDidChange()`.
 	 */
-	onItemHeightChange(i) {
-		warn('`.onItemHeightChange(i)` method was renamed to `.onItemHeightDidChange(i)`')
-		this.onItemHeightDidChange(i)
+	onItemHeightChange(item) {
+		warn('`.onItemHeightChange(item)` method was renamed to `.onItemHeightDidChange(item)`')
+		this.onItemHeightDidChange(item)
 	}
 
 	/**
 	 * Forces a re-measure of an item's height.
-	 * @param  {number} i — Item index
+	 * @param {any} item — Item. Legacy argument variant: Item index.
 	 */
-	onItemHeightDidChange(i) {
+	onItemHeightDidChange(itemOrIndex) {
 		// See the comments in the `setItemState()` function below for the rationale
 		// on why the `hasToBeStarted()` check was commented out.
 		// this.hasToBeStarted()
-		this._onItemHeightDidChange(i)
+		this._onItemHeightDidChange(itemOrIndex)
 	}
 
 	/**
 	 * Updates an item's state in `state.itemStates[]`.
-	 * @param  {number} i — Item index
-	 * @param  {any} i — Item's new state
+	 * @param  {any} item — Item. Legacy argument variant: Item index.
+	 * @param  {any} newItemState — Item's new state
 	 */
-	setItemState(i, newItemState) {
+	setItemState(itemOrIndex, newItemState) {
 		// There is an issue in React 18.2.0 when `useInsertionEffect()` doesn't run twice
 		// on mount unlike `useLayoutEffect()` in "strict" mode. That causes a bug in a React
 		// implementation of the `virtual-scroller`.
@@ -285,13 +294,13 @@ export default class VirtualScroller {
 		// Commenting it out wouldn't result in any potential bugs because the code would work correctly
 		// in both cases.
 		// this.hasToBeStarted()
-		this._setItemState(i, newItemState)
+		this._setItemState(itemOrIndex, newItemState)
 	}
 
 	// (deprecated)
 	// Use `.setItemState()` method name instead.
-	onItemStateChange(i, newItemState) {
-		this.setItemState(i, newItemState)
+	onItemStateChange(item, newItemState) {
+		this.setItemState(item, newItemState)
 	}
 
 	/**

package/source/VirtualScroller.layout.js

@@ -101,7 +101,7 @@ export default function() {
 		// or an "Expand YouTube video" button, which would result
 		// in the actual height of the list item being different
 		// from what has been initially measured in `this.itemHeights[i]`,
-		// if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightDidChange(i)`.
+		// if the developer didn't call `.setItemState(item, newState)` and `.onItemHeightDidChange(item)`.
 		if (!validateWillBeHiddenItemHeightsAreAccurate.call(this, firstShownItemIndex, lastShownItemIndex)) {
 			log('~ Because some of the will-be-hidden item heights (listed above) have changed since they\'ve last been measured, redo layout. ~')
 			// Redo layout, now with the correct item heights.
@@ -135,7 +135,7 @@ export default function() {
 		log('Last shown item index', lastShownItemIndex)
 		log('Before items height', beforeItemsHeight)
 		log('After items height (actual or estimated)', afterItemsHeight)
-		log('Average item height (used for estimated after items height calculation)', this.itemHeights.getAverage())
+		log('Average item height (used for estimated after items height calculation)', this.getAverageItemHeight())
 		if (isDebug()) {
 			log('Item heights', this.getState().itemHeights.slice())
 			log('Item states', this.getState().itemStates.slice())
@@ -177,9 +177,9 @@ export default function() {
 			// Instead of using a `this.previouslyCalculatedLayout` instance variable,
 			// this code could use `this.getState()` because it reflects what's currently on screen,
 			// but there's a single edge case when it could go out of sync —
-			// updating item heights externally via `.onItemHeightDidChange(i)`.
+			// updating item heights externally via `.onItemHeightDidChange(item)`.
 			//
-			// If, for example, an item height was updated externally via `.onItemHeightDidChange(i)`
+			// If, for example, an item height was updated externally via `.onItemHeightDidChange(item)`
 			// then `this.getState().itemHeights` would get updated immediately but
 			// `this.getState().beforeItemsHeight` or `this.getState().afterItemsHeight`
 			// would still correspond to the previous item height, so those would be "stale".
@@ -270,7 +270,7 @@ export default function() {
 	 * or an "Expand YouTube video" button, which would result
 	 * in the actual height of the list item being different
 	 * from what has been initially measured in `this.itemHeights[i]`,
-	 * if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightDidChange(i)`.
+	 * if the developer didn't call `.setItemState(item, newState)` and `.onItemHeightDidChange(item)`.
 	 */
 	function validateWillBeHiddenItemHeightsAreAccurate(firstShownItemIndex, lastShownItemIndex) {
 		let isValid = true
@@ -282,26 +282,26 @@ export default function() {
 				// The item will be hidden. Re-measure its height.
 				// The rationale is that there could be a situation when an item's
 				// height has changed, and the developer has properly added an
-				// `.onItemHeightDidChange(i)` call to notify `VirtualScroller`
+				// `.onItemHeightDidChange(item)` call to notify `VirtualScroller`
 				// about that change, but at the same time that wouldn't work.
 				// For example, suppose there's a list of several items on a page,
 				// and those items are in "minimized" state (having height 100px).
 				// Then, a user clicks an "Expand all items" button, and all items
 				// in the list are expanded (expanded item height is gonna be 700px).
-				// `VirtualScroller` demands that `.onItemHeightDidChange(i)` is called
+				// `VirtualScroller` demands that `.onItemHeightDidChange(item)` is called
 				// in such cases, and the developer has properly added the code to do that.
 				// So, if there were 10 "minimized" items visible on a page, then there
-				// will be 10 individual `.onItemHeightDidChange(i)` calls. No issues so far.
-				// But, as the first `.onItemHeightDidChange(i)` call executes, it immediately
+				// will be 10 individual `.onItemHeightDidChange(item)` calls. No issues so far.
+				// But, as the first `.onItemHeightDidChange(item)` call executes, it immediately
 				// ("synchronously") triggers a re-layout, and that re-layout finds out
 				// that now, because the first item is big, it occupies most of the screen
 				// space, and only the first 3 items are visible on screen instead of 10,
 				// and so it leaves the first 3 items mounted and unmounts the rest 7.
 				// Then, after `VirtualScroller` has rerendered, the code returns to
-				// where it was executing, and calls `.onItemHeightDidChange(i)` for the
+				// where it was executing, and calls `.onItemHeightDidChange(item)` for the
 				// second item. It also triggers an immediate re-layout that finds out
 				// that only the first 2 items are visible on screen, and it unmounts
-				// the third one too. After that, it calls `.onItemHeightDidChange(i)`
+				// the third one too. After that, it calls `.onItemHeightDidChange(item)`
 				// for the third item, but that item is no longer rendered, so its height
 				// can't be measured, and the same's for all the rest of the original 10 items.
 				// So, even though the developer has written their code properly, the
@@ -319,7 +319,7 @@ export default function() {
 						updatePreviouslyCalculatedLayoutOnItemHeightChange.call(this, i, previouslyMeasuredItemHeight, actualItemHeight)
 					}
 					isValid = false
-					warn('Item index', i, 'is no longer visible and will be unmounted. Its height has changed from', previouslyMeasuredItemHeight, 'to', actualItemHeight, 'since it was last measured. This is not necessarily a bug, and could happen, for example, on screen width change, or when there\'re several `onItemHeightDidChange(i)` calls issued at the same time, and the first one triggers a re-layout before the rest of them have had a chance to be executed.')
+					warn('Item index', i, 'is no longer visible and will be unmounted. Its height has changed from', previouslyMeasuredItemHeight, 'to', actualItemHeight, 'since it was last measured. This is not necessarily a bug, and could happen, for example, on screen width change, or when there\'re several `onItemHeightDidChange(item)` calls issued at the same time, and the first one triggers a re-layout before the rest of them have had a chance to be executed.')
 				}
 			}
 			i++
@@ -372,9 +372,15 @@ export default function() {
 		return listTopOffset
 	}
 
-	this._onItemHeightDidChange = (i) => {
-		log('~ On Item Height Did Change was called ~')
-		log('Item index', i)
+	this._onItemHeightDidChange = (itemOrIndex) => {
+		// Item index.
+		const i = this._getItemIndexByItemOrIndex(itemOrIndex)
+
+		// If the item wasn't found, the error was already reported,
+		// so just don't do anything else.
+		if (i === undefined) {
+			return
+		}
 
 		const {
 			itemHeights,
@@ -382,39 +388,42 @@ export default function() {
 			lastShownItemIndex
 		} = this.getState()
 
+		log('~ On Item Height Did Change was called ~')
+		log('Item index', i)
+
 		// Check if the item is still rendered.
 		if (!(i >= firstShownItemIndex && i <= lastShownItemIndex)) {
 			// There could be valid cases when an item is no longer rendered
-			// by the time `.onItemHeightDidChange(i)` gets called.
+			// by the time `.onItemHeightDidChange(item)` gets called.
 			// For example, suppose there's a list of several items on a page,
 			// and those items are in "minimized" state (having height 100px).
 			// Then, a user clicks an "Expand all items" button, and all items
 			// in the list are expanded (expanded item height is gonna be 700px).
-			// `VirtualScroller` demands that `.onItemHeightDidChange(i)` is called
+			// `VirtualScroller` demands that `.onItemHeightDidChange(item)` is called
 			// in such cases, and the developer has properly added the code to do that.
 			// So, if there were 10 "minimized" items visible on a page, then there
-			// will be 10 individual `.onItemHeightDidChange(i)` calls. No issues so far.
-			// But, as the first `.onItemHeightDidChange(i)` call executes, it immediately
+			// will be 10 individual `.onItemHeightDidChange(item)` calls. No issues so far.
+			// But, as the first `.onItemHeightDidChange(item)` call executes, it immediately
 			// ("synchronously") triggers a re-layout, and that re-layout finds out
 			// that now, because the first item is big, it occupies most of the screen
 			// space, and only the first 3 items are visible on screen instead of 10,
 			// and so it leaves the first 3 items mounted and unmounts the rest 7.
 			// Then, after `VirtualScroller` has rerendered, the code returns to
-			// where it was executing, and calls `.onItemHeightDidChange(i)` for the
+			// where it was executing, and calls `.onItemHeightDidChange(item)` for the
 			// second item. It also triggers an immediate re-layout that finds out
 			// that only the first 2 items are visible on screen, and it unmounts
-			// the third one too. After that, it calls `.onItemHeightDidChange(i)`
+			// the third one too. After that, it calls `.onItemHeightDidChange(item)`
 			// for the third item, but that item is no longer rendered, so its height
 			// can't be measured, and the same's for all the rest of the original 10 items.
 			// So, even though the developer has written their code properly, there're
 			// still situations when the item could be no longer rendered by the time
-			// `.onItemHeightDidChange(i)` gets called.
-			return warn('The item is no longer rendered. This is not necessarily a bug, and could happen, for example, when when a developer calls `onItemHeightDidChange(i)` while looping through a batch of items.')
+			// `.onItemHeightDidChange(item)` gets called.
+			return warn('The item is no longer rendered. This is not necessarily a bug, and could happen, for example, when when a developer calls `onItemHeightDidChange(item)` while looping through a batch of items.')
 		}
 
 		const previousHeight = itemHeights[i]
 		if (previousHeight === undefined) {
-			// There're valid cases when the item still hasn't been measured and `onItemHeightDidChange()`
+			// There're valid cases when the item still hasn't been measured and `onItemHeightDidChange(item)`
 			// function was called for it. That's because measuring items is only done after the `VirtualScroller`
 			// has `start()`ed. But it's not neccessarily `start()`ed by the time it has been rendered (mounted).
 			// For example, the React component `<VirtualScroller/>` provides an `readyToStart={false}` property
@@ -435,7 +444,7 @@ export default function() {
 		try {
 			newHeight = remeasureItemHeight.call(this, i)
 		} catch (error) {
-			// Successfully finishing an `onItemHeightDidChange(i)` call is not considered
+			// Successfully finishing an `onItemHeightDidChange(item)` call is not considered
 			// critical for `VirtualScroller`'s operation, so such errors could be ignored.
 			if (error instanceof ItemNotRenderedError) {
 				return reportError(`"onItemHeightDidChange()" has been called for item index ${i} but the item is not currently rendered and can\'t be measured. The exact error was: ${error.message}`)
@@ -460,7 +469,7 @@ export default function() {
 			// Recalculate layout.
 			//
 			// If the `VirtualScroller` is already waiting for a state update to be rendered,
-			// delay `onItemHeightDidChange(i)`'s re-layout until that state update is rendered.
+			// delay `onItemHeightDidChange(item)`'s re-layout until that state update is rendered.
 			// The reason is that React `<VirtualScroller/>`'s `onHeightDidChange()` is meant to
 			// be called inside `useLayoutEffect()` hook. Due to how React is implemented internally,
 			// that might happen in the middle of the currently pending `setState()` operation
@@ -503,8 +512,12 @@ export default function() {
 		// scroll past the screen height, because they'd stop to read through
 		// the newly visible items first, and when they do stop scrolling, that's
 		// when layout gets recalculated).
-		const renderAheadMarginRatio = 1 // in scrollable container heights.
-		return this.scrollableContainer.getHeight() * renderAheadMarginRatio
+		return this.scrollableContainer.getHeight() * this.getPrerenderMarginRatio()
+	}
+
+	this.getPrerenderMarginRatio = () => {
+		// See the readme for the description of `prerenderMarginRatio` option.
+		return 1 // in scrollable container heights.
 	}
 
 	/**

package/source/VirtualScroller.onContainerResize.js

@@ -134,8 +134,7 @@ export default function() {
 				columnsCount,
 				itemHeights: this.beforeResize.snapshotBeforeResizeItemHeights({
 					firstShownItemIndex,
-					newFirstShownItemIndex,
-					newColumnsCount
+					newFirstShownItemIndex
 				})
 			}
 		}