A high-level wrapper should supply either getState/setState functions, or onStateChange function (or both of them), and those functions are gonna be responsible for rendering the actual list using the information from state.

The main state properties are:

• items: any[] — The list of items (can be updated via .setItems()).

• firstShownItemIndex: number — The index of the first item that should be rendered.

• lastShownItemIndex: number — The index of the last item that should be rendered.

• beforeItemsHeight: number — The padding-top which should be applied to the "container" element: it emulates all items before firstShownItemIndex as if they were rendered.

• afterItemsHeight: number — The padding-bottom which should be applied to the "container" element: it emulates all items after lastShownItemIndex as if they were rendered.

The following state properties are only used for saving and restoring VirtualScroller state, and normally shouldn't be accessed:

• itemStates: object?[] — The states of all items. Any change in an item's appearance while it's rendered must be reflected in changing that item's state by calling .onItemStateChange(i, itemState) instance method (described below): this way, the item's state is preserved when it's shown next time after being hidden due to going off screen. For example, if an item is a social media comment, and there's a "Show more"/"Show less" button that shows the full text of the comment, then it must call .onItemStateChange(i, { showMore: true/false }) every time.

• itemHeights: number?[] — The measured heights of all items. If an item's height hasn't been measured yet then it's undefined. By default, items are only measured once: when they're initially rendered. If an item's height changes afterwards, then .onItemHeightChange(i) instance method must be called (described below), otherwise VirtualScroller's calculations will be off. For example, if an item is a social media comment, and there's a "Show more"/"Show less" button that shows the full text of the comment, then it must call .onItemHeightChange(i) every time. And every change in an item's height must come as a result of changing some kind of state, be it the item's state in VirtualScroller via .onItemStateChange(), or some other state managed by the application.

• verticalSpacing: number? — Vertical item spacing. Is undefined until it has been measured. Is only measured once, when at least two rows of items have been rendered.

• columnsCount: number? — The count of items in a row. Is undefined if no getColumnsCount() parameter has been passed to VirtualScroller.

import VirtualScroller from 'virtual-scroller'

const items = [...]

const getItemsContainerElement = () => ...

const virtualScroller = new VirtualScroller(getItemsContainerElement, items, {
  onStateChange(state) {
    // Re-render the list based on its state:
    // * items
    // * firstShownItemIndex
    // * lastShownItemIndex
    // * beforeItemsHeight
    // * afterItemsHeight
  }
})

// Start listening to scroll events.
virtualScroller.listen()

// Stop listening to scroll events.
virtualScroller.stop()

• getItemsContainerElement() function returns the list "element" that is gonna contain all list item "elements".
• items is the list of items.
• onStateChange(state) is one of the available list options.

import VirtualScroller from 'virtual-scroller'

const items = [
  { title: 'Apple' },
  { title: 'Banana' },
  { title: 'Cranberry' }
]

function renderItem(item) {
  const div = document.createElement('div')
  div.innerText = item.title
  return div
}

const container = document.getElementById('list')

function onStateChange(newState, prevState) {
  const {
    items,
    beforeItemsHeight,
    afterItemsHeight,
    firstShownItemIndex,
    lastShownItemIndex
  } = newState
  // Set `paddingTop` and `paddingBottom` on the container element:
  // it emulates the non-visible items as if they were rendered.
  container.style.paddingTop = Math.round(beforeItemsHeight) + 'px'
  container.style.paddingBottom = Math.round(afterItemsHeight) + 'px'
  // Perform an intelligent "diff" re-render as the user scrolls the page.
  // This also requires that the list of `items` hasn't been changed.
  // On initial render, `prevState` is `undefined`.
  if (prevState && items === prevState.items) {
    // Remove no longer visible items.
    let i = prevState.lastShownItemIndex
    while (i >= prevState.firstShownItemIndex) {
      if (i >= firstShownItemIndex && i <= lastShownItemIndex) {
        // The item is still visible.
      } else {
        // The item is no longer visible. Remove it.
        container.removeChild(container.childNodes[i - prevState.firstShownItemIndex])
      }
      i--
    }
    // Add newly visible items.
    let prependBefore = container.firstChild
    let i = firstShownItemIndex
    while (i <= lastShownItemIndex) {
      if (i >= prevState.firstShownItemIndex && i <= prevState.lastShownItemIndex) {
        // The item is already being rendered.
        // Next items will be appended rather than prepended.
        prependBefore = undefined
      } else {
        if (prependBefore) {
          container.insertBefore(renderItem(items[i]), prependBefore)
        } else {
          container.appendChild(renderItem(items[i]))
        }
      }
      i++
    }
  } else {
    // Re-render the list from scratch.
    while (container.firstChild) {
      container.removeChild(container.firstChild)
    }
    let i = firstShownItemIndex
    while (i <= lastShownItemIndex) {
      container.appendChild(renderItem(items[i]))
      i++
    }
  }
}

const options = { onStateChange }

const virtualScroller = new VirtualScroller(() => element, items, options)

// Start VirtualScroller listening for scroll events.
virtualScroller.listen()

// Stop VirtualScroller listening for scroll events
// when the user navigates to another page:
// router.onPageUnload(virtualScroller.stop)

• estimatedItemHeight: number — Is used for the initial render of the list: determines how many list items are rendered initially to cover the screen height plus some extra vertical margin (called "prerender margin") for future scrolling. If not set then the list first renders just the first item, measures it, and then assumes it to be the estimatedItemHeight from which it calculates how many items to show on the second render pass to fill the screen height plus the "prerender margin". Therefore, this setting is only for the initial render minor optimization and is not required.

• prerenderMargin — The list component renders not only the items that're currently visible but also the items that lie within some extra vertical margin (called "prerender margin") on top and bottom for future scrolling: this way, there'll be significantly less layout recalculations as the user scrolls, because now it doesn't have to recalculate layout on each scroll event. By default, the "prerender margin" is equal to the screen height: this seems to be the optimal value for "Page Up" / "Page Down" navigation and optimized mouse wheel scrolling. This parameter is currently ignored because the default value seems to fit all possible use cases.

• state: object — The initial state for VirtualScroller. Can be used, for example, to quicky restore the list when it's re-rendered on "Back" navigation.

• customState: object — (advanced) The initial "custom" state for VirtualScroller. It can be used to initialize the "custom" part of VirtualScroller state in cases when VirtualScroller state is used to store some "custom" list state.

• getState(): object — (advanced) By default, VirtualScroller manages state internally by storing it in an instance variable. For more control, the state could be managed externally, in which case a developer should supply getState/setState options, in which case getState should return the externally stored VirtualScroller state. React VirtualScroller component implementation uses this option.

• setState(stateUpdate: object, { willUpdateState, didUpdateState }) — (advanced) By default, VirtualScroller manages state internally by storing it in an instance variable. For more control, the state could be managed externally, in which case a developer should supply getState/setState options, in which case setState should update the externally stored VirtualScroller state (including setting the initial state), and it should do that by merging the previous state with the stateUpdate argument. setState must also call two functions: willUpdateState(newState, prevState) right before the state is updated and didUpdateState(prevState) right after the state is updated. The list should be re-rendered as part of either setState or onStateChange. setState could be "asynchronous", that is when state updates aren't applied immediately and are instead queued and then applied in a single state update for performance. React VirtualScroller component implementation uses this option.

• onStateChange(newState: object, prevState: object?) — Is called whenever VirtualScroller state is updated (including setting the initial state). Is not called when individual item heights (including "before resize" ones) or states are updated: instead, individual item heights or states are updated in-place — state.itemHeights[i] = newItemHeight or state.itemStates[i] = newItemState. That's because those state properties are the ones that don’t affect the presentation, so there's no need to re-render the list when those do change — updating those properties is just an effect of some change rather than cause for one. In order for a VirtualScroller implementation to work, a developer must either supply getState/setState options or onStateChange option (or both). The list should be re-rendered as part of either setState or onStateChange.

• scrollableContainer: Element — (advanced) If the list is being rendered in a "scrollable container" (for example, if one of the parent elements of the list is styled with max-height and overflow: auto), then passing the "scrollable container" DOM Element is required for correct operation. This feature is considered experimental. The width and height of the scrollableContainer shouldn't change unless window is resized.

• initialScrollPosition: number — If passed, the page will be scrolled to this scrollY position.

• onScrollPositionChange(scrollY: number) — Is called whenever a user scrolls the page.

• bypass: boolean — Pass true to turn off VirtualScroller behavior and just render the full list of items.

• getItemId(item) — (advanced) When items are dynamically updated via .setItems(), VirtualScroller detects an "incremental" update by comparing "new" and "old" item "references": this way, VirtualScroller can understand that the "new" items are (mostly) the same as the "old" items when some items get prepended or appended to the list, in which case it doesn't re-render the whole list from scratch, but rather just renders the "new" items that got prepended or appended. Sometimes though, some of the "old" items might get updated: for example, if items is a list of comments, then some of those comments might get edited in-between the refreshes. In that case, the edited comment object reference should change in order to indicate that the comment's content has changed and that the comment should be re-rendered (at least that's how it has to be done in React world). At the same time, changing the edited comment object reference would break VirtualScroller's "incremental" update detection, and it would re-render the whole list of comments from scratch, which is not what it should be doing in such cases. So, in cases like this, VirtualScroller should have some way to understand that the updated item, even if its object reference has changed, is still the same as the old one, so that it doesn't break "incremental" update detection. For that, getItemId(item) parameter could be passed, which VirtualScroller would use to compare "old" and "new" items (instead of the default "reference equality" check), and that would fix the "re-rendering the whole list from scratch" issue. It can also be used when items are fetched from an external API, in which case all item object references change on every such fetch.

• onItemInitialRender(item) — Is called for each item when it's about to be rendered for the first time. Is guaranteed to be called at least once for each item rendered, though, in "asynchronous" rendering systems like React, it could be called multiple times for a given item, because "an item is calculated to be rendered" doesn't necessarily mean that the actual rendering will take place before a later calculation supercedes the former one. This function can be used to somehow "initialize" items before they're rendered for the first time. For example, consider a list of items that must be somehow "preprocessed" (parsed, enhanced, etc) before being rendered, and such "preprocessing" puts some load on the CPU (and therefore takes some time). In such case, instead of "preprocessing" the whole list of items up front, a developer could "preprocess" the items as they're being rendered, thereby eliminating any associated lag or freezing that would be inevitable have all the items been "preprocessed" up front. If a user only wants to see a few of the items, "preprocessing" all the items up front would simply be a waste.

• shouldUpdateLayoutOnScreenResize(event: Event): boolean — By default, VirtualScroller always performs a re-layout on window resize event. The resize event is not only triggered when a user resizes the window itself: it's also triggered when the user switches into (and out of) fullscreen mode. By default, VirtualScroller performs a re-layout on all window resize events, except for ones that don't result in actual window width or height change, and except for cases when, for example, a video somewhere in a list is maximized into fullscreen. There still can be other "custom" cases: for example, when an application uses a custom "slideshow" component (rendered outside of the list DOM element) that goes into fullscreen when a user clicks a picture or a video in the list. For such "custom" cases shouldUpdateLayoutOnScreenResize(event) option / property can be specified.

• measureItemsBatchSize: number — (advanced) (experimental) Imagine a situation when a user doesn't gradually scroll through a huge list but instead hits an End key to scroll right to the end of such huge list: this will result in the whole list rendering at once (because an item needs to know the height of all previous items in order to render at correct scroll position) which could be CPU-intensive in some cases (for example, when using React due to its slow performance when initially rendering components on a page). To prevent freezing the UI in the process, a measureItemsBatchSize could be configured, that would limit the maximum count of items that're being rendered in a single pass for measuring their height: if measureItemsBatchSize is configured, then such items will be rendered and measured in batches. By default it's set to 100. This is an experimental feature and could be removed in future non-major versions of this library. For example, the future React 17 will come with Fiber rendering engine that is said to resolve such freezing issues internally. In that case, introducing this option may be reconsidered.

• getColumnsCount(container: ScrollableContainer): number — (advanced) Provides support for "grid" layout. The container argument provides a .getWidth() method.

• listen() — Starts VirtualScroller listening for scroll events. Should be called immediately after the list has been rendered on a page.

• stop() — Stops VirtualScroller listening for scroll events. Should be called when the list is about to be removed from the page. Once stopped, a VirtualScroller can't be restarted.

• getState(): object — Returns VirtualScroller state. Is used for React VirtualScroller component implementation.

• onItemHeightChange(i: number) — Must be called whenever a list item's height changes (for example, when a user clicks an "Expand"/"Collapse" button of a list item): it re-measures the item's height and updates VirtualScroller layout. Every change in an item's height must come as a result of changing some kind of state, be it the item's state in VirtualScroller via .onItemStateChange(), or some other state managed by the application. Implementation-wise, calling onItemHeightChange() manually could be replaced with detecting item height changes automatically via Resize Observer.

• onItemStateChange(i: number, itemState: object?) — Updates a list item's state inside VirtualScroller state. Must be called whenever an item's "state" changes: this way, the item's state is preserved when the item is unmounted due to going off screen, and then restored when the item is on screen again. Calling onItemStateChange() doesn't trigger a re-layout of VirtualScroller because changing a list item's state doesn't necessarily mean a change of its height, so a re-layout might not be required. If an item's height did change as a result of changing its state, then VirtualScroller layout must be updated, and to do that, call onItemHeightChange(i) after calling onItemStateChange(). For example, consider a social network feed, each post optionally having an attachment. Suppose there's a post in the feed having a YouTube video attachment. The attachment is initially shown as a small thumbnail that expands into a full-sized embedded YouTube video player when a user clicks on it. If the expanded/collapsed state of such attachment isn't been managed in VirtualScroller, then, when the user expands the video, then scrolls down so that the post with the video is no longer visible and is unmounted as a result, then scrolls back up so that the post with the video is visible again, the video's expanded state would be lost, and it would be rendered as a small thumbnail as if the user didn't click on it. And don't forget about calling onItemHeightChange(i) in such cases: if onItemHeightChange(i) isn't called after expanding the thumbnail into a video player, then the scroll position would "jump" when such item goes off screen, because VirtualScroller would have based its calculations on the initially measured item height, not the "expanded" one.

• getItemScrollPosition(i: number): number? — Returns an item's scroll position inside the scrollable container. Returns undefined if any of the items before this item haven't been rendered yet.

• setItems(newItems: any[], options: object?) — Updates VirtualScroller items. For example, it can be used to prepend or append new items to the list. See Dynamically Loaded Lists section for more details. Available options: preserveScrollPositionOnPrependItems: boolean — Set to true to enable "restore scroll position after prepending new items" feature (should be used when implementing a "Show previous items" button).

• updateLayout() — (advanced) Triggers a re-layout of VirtualScroller. It's what's called every time on page scroll or window resize. You most likely won't ever need to call this method manually. Still, it can be called manually when the list's top position changes not as a result of scrolling the page or resizing the window. For example, if some DOM elements above the list are removed (like a closeable "info" panel) or collapsed (like an "accordion" panel), then the list's top position changes, which means that now some of the previoulsy shown items might go off screen, and the user might be seeing a blank area where items haven't been rendered yet because they were off-screen during the previous VirtualScroller layout. VirtualScroller automatically performs a layout only on page scroll or window resize; in all other cases, when layout needs to be re-run, call it manually via this instance method.

DOM VirtualScroller constructor takes arguments:

• container — Items list container DOM Element.
• items — The items list.
• renderItem(item) — Renders an item as a DOM Element.
• options — VirtualScroller options.

Additional options:

• onItemUnmount(itemElement) — Is called after a VirtualScroller item DOM Element is unmounted. Can be used to add DOM Element "pooling".

• setItems(items, options) — A proxy for the corresponding VirtualScroller method.

• onItemHeightChange(i) — A proxy for the corresponding VirtualScroller method.

• onItemStateChange(i, itemState) — A proxy for the corresponding VirtualScroller method.

• stop() — A proxy for the corresponding VirtualScroller method.

• items — The items list.

• itemComponent — List item component. For best performance, make sure it's a React.PureComponent or a React.memo(), otherwise it'll be re-rendering as the user scrolls and new items get shown or older ones get hidden.

• itemComponentProps: object — (optional) The props passed to itemComponent.

• as — A component used as a container for the list items. Is "div" by default.

• estimatedItemHeight: number — (optional) The estimatedItemHeight option of VirtualScroller class.

• bypass: boolean — (optional) The bypass option of VirtualScroller class.

• preserveScrollPositionOnPrependItems: boolean — (optional) The preserveScrollPositionOnPrependItems option of VirtualScroller.setItems() method.

• measureItemsBatchSize: number — (optional) The measureItemsBatchSize option of VirtualScroller.

• getColumnsCount(): number — (optional) The getColumnsCount() option of VirtualScroller.

• getItemId(item): any — (optional) The getItemId option of VirtualScroller class. The React component also uses it as a source for a React key for rendering an item. If getItemId() is not supplied, then item keys are autogenerated from a random-generated prefix (that changes every time items are updated) and an item index. Can be used to prevent <VirtualScroller/> from re-rendering all visible items every time items property is updated.

• onItemInitialRender(item) — (optional) The onItemInitialRender option of VirtualScroller class.

• shouldUpdateLayoutOnScreenResize(event) — (optional) The shouldUpdateLayoutOnScreenResize option of VirtualScroller class.

• initialState: object — (optional) The initial state for VirtualScroller: the state option of VirtualScroller. For example, can be used to quicky restore the list on "Back" navigation.

• initialCustomState: object — (advanced) (optional) The initial "custom" state for VirtualScroller: the customState option of VirtualScroller. It can be used to initialize the "custom" part of VirtualScroller state in cases when VirtualScroller state is used to store some "custom" list state.

• onStateChange(newState: object, prevState: object) — (optional) Is called whenever VirtualScroller state is updated (including setting the initial state). For example, can be used to keep VirtualScroller state copy in an instance variable and later in componentWillUnmount() persist it somewhere in global application state for quickly restoring it later on "Back" navigation:

import {
  getVirtualScrollerState,
  setVirtualScrollerState
} from './globalState'

class Example extends React.Component {
  componentWillUnmount() {
    saveVirtualScrollerState(this.virtualScrollerState)
  }
  render() {
    return (
      <VirtualScroller
        items={...}
        itemComponent={...}
        state={hasUserNavigatedBack ? getVirtualScrollerState() : undefined}
        onStateChange={state => this.virtualScrollerState = state}/>
    )
  }
}

• children — The list item (an element of the items array).

• state — (advanced) List item element state. If a list item element renders differently depending on some "state" then that state should be "managed" (stored and later restored) as the list item becomes hidden and later visible again. See onStateChange property description.

• onStateChange(newItemState) — (advanced) Can be called to save the list item element state when it changes. The need for saving and restoring list item element state arises because item elements get unmounted as they go off screen. For example, consider a social network feed where feed items (posts) can be expanded or collapsed via a "Show more"/"Show less" button. Suppose a user clicks a "Show more" button on a post resulting in that post expanding in height. Then the user scrolls down and since the post is no longer visible it gets unmounted. Since no state is preserved by default, when the user scrolls back up and the post gets mounted again, its previous state will be lost and it will render as a collapsed post instead of an expanded one, resulting in a perceived "jump" of page content by the difference in height of the post being expanded and collapsed. To prevent that, define a "state" of an item element — for example, { expanded: true } — and then call onStateChange(newState) every time the item element state changes, and read that state from the state property when rendering the item element. Calling onStateChange() simply updates the item element state, and doesn't re-render the item element: it's just a proxy for VirtualScroller.onItemStateChange(i, itemState).

• onHeightChange() — (advanced) Call this function whenever the item element height changes. In the example above, onHeightChange() should be called when a user clicks a "Show more"/"Show less" button because that results in a change of the item element's height, so VirtualScroller should re-measure it in order for its internal calculations to stay correct. This is simply a proxy for VirtualScroller.onItemHeightChange(i).

• renderItem(i) — Calls .forceUpdate() on the itemComponent instance for the item with index i. Does nothing if the item isn't currently rendered. Is only supported for itemComponents that are React.Components. The i item index argument could be replaced with the item object itself, in which case <VirtualScroller/> will find the index of the item by itself.

• updateLayout() — A proxy for the corresponding VirtualScroller method.

When using virtual-scroller/dom component, a developer should call .setItems(newItems) instance method in order to update items.

When using virtual-scroller/react React component, it calls .setItems(newItems) method automatically when new items property is passed.

The basic equality check (===) is used to intelligently compare newItems to the existing items. If getItemId() parameter is passed, then items are compared by their ids rather than by themselves. If a simple append and/or prepend operation is detected, then the update is an "incremental" one, and the list seamlessly transitions from the current state to the new state, preserving its state and scroll position. If, however, the items have been updated in such a way that it's not a simple append and/or prepend operation, then such update is a "non-incremental" one, and the entire list is rerendered from scratch, losing its state and resetting the scroll position. There're valid use cases for both situations.

For example, suppose a user navigates to a page where a list of items: object[] is shown using a VirtualScroller. When a user scrolls down to the last item in the list, a developer might want to query the database for the newly added items, and then show those new items to the user. In that case, the developer could send a query to the API with afterId: number parameter being the id: number of the last item in the list, and the API would then return a list of the newItems: object[] whose id: number is greater than the afterId: number parameter. Then, the developer would append the newItems: object[] to the items: object[], and then call VirtualScroller.setItems() with the updated items: object[], resulting in a "seamless" update of the list, preserving its state and scroll position.

Another example. Suppose a user navigates to a page where they can filter a huge list by a query entered in a search bar. In that case, when the user edits the query in the search bar, VirtualScroller.setItems() method is called with a list of filtered items, and the entire list is rerendered from scratch. In this case, it's ok to reset the VirtualScroller state and the scroll position.

When new items are appended to the list, the page scroll position remains unchanged. Same's for prepending new items to the list: the scroll position of the page stays the same, resulting in the list "jumping" down when new items get prepended. To fix that, pass preserveScrollPositionOnPrependItems: true option to the VirtualScroller. When using virtual-scroller/dom component, pass that option when creating a new instance, and when using virtual-scroller/react React component, pass preserveScrollPositionOnPrependItems property.

For implementing "infinite scroll" lists, a developer could also use on-scroll-to component.

When the user scrolls up past the "prerender margin", which equals to the screen height by default, the list content does "jump" because the web browser doesn't want to apply the scroll position correction while scrolling for some weird reason. Looks like a bug in the web browser.

[virtual-scroller] The user is scrolling: perform a re-layout when they stop scrolling
Current scroll position: 7989
[virtual-scroller] The user is scrolling: perform a re-layout when they stop scrolling
Current scroll position: 7972
[virtual-scroller] The user is scrolling: perform a re-layout when they stop scrolling
Current scroll position: 7957
[virtual-scroller] The user has scrolled far enough: perform a re-layout
[virtual-scroller] ~ Update Layout (on scroll) ~
...
[virtual-scroller] ~ Rendered ~
[virtual-scroller] State ...
[virtual-scroller] ~ Measure item heights ~
[virtual-scroller] Item index 27 height 232
[virtual-scroller] Item index 28 height 178
[virtual-scroller] ~ Clean up "before resize" item heights and correct scroll position ~
[virtual-scroller] For item indexes from 27 to 28 — drop "before resize" heights [340, 259]
[virtual-scroller] Correct scroll position by -189
Scroll to position: 7768
[virtual-scroller] Set state ...
[virtual-scroller] ~ Rendered ~
[virtual-scroller] State ...
Current scroll position: 7944
[virtual-scroller] The user is scrolling: perform a re-layout when they stop scrolling
Current scroll position: 7933
[virtual-scroller] The user is scrolling: perform a re-layout when they stop scrolling
Current scroll position: 7924
[virtual-scroller] The user is scrolling: perform a re-layout when they stop scrolling
...

var listener = () => {
  console.log('Current scroll position:', window.pageYOffset)
}
document.addEventListener('scroll', listener)
var unlisten = () => document.removeEventListener('scroll', listener)

// Also add `console.log('Scroll to position:', scrollY)` in
// `scrollToY()` method in `./source/DOM/ScrollableContainer.js`.

Also, pressing the "Home" key wouldn't scroll up past the "prerender margin", which is equal to the screen height by default. The reason is the same: applying scroll position correction while the "Home" key is pressed cancels the effect of the "Home" button.

A possible workaround for those bugs would be postponing scroll position correction until the user stops scrolling, and instead change margin-bottom of some "spacer" element at the top of the list (or maybe even before the list). When the user stops scrolling, the scroll position would get corrected by the value of margin-bottom of that "spacer" element, after which the margin-bottom value on that "spacer" element would be reset. But this type of a workaround would only work in a DOM environment because it requires the support of "negative" margin.

For now, I don't see it as a bug that would be worth fixing. The user could just refresh the page, or not scroll up at all because they've already seen that content.

VirtualScroller calculates the shown item indexes when its .onMount() method is called, but if the page styles are applied after VirtualScroller is mounted (for example, if styles are applied via javascript, like Webpack does it in dev mode with its style-loader) then the list might not render correctly and will only show the first item. The reason for that is because calling .getBoundingClientRect() on the list container DOM element on mount returns "incorrect" top position because the styles haven't been applied yet, and so VirtualScroller thinks it's offscreen.

For example, consider a page:

<div class="page">
  <nav class="sidebar">...</nav>
  <main>...</main>
</div>

The sidebar is styled as position: fixed, but until the page styles have been applied it's gonna be a regular <div/> meaning that <main/> will be rendered below the sidebar causing it to be offscreen and so the list will only render the first item. Then, the page styles are loaded and applied and the sidebar is now position: fixed so <main/> is now rendered at the top of the page but VirtualScroller's .render() has already been called and it won't re-render until the user scrolls or the window is resized.

This type of a bug doesn't occur in production, but it can appear in development mode when using Webpack. The workaround VirtualScroller implements for such cases is calling .getBoundingClientRect() on the list container DOM element periodically (every second) to check if the top coordinate has changed as a result of CSS being applied: if it has then it recalculates the shown item indexes and re-renders.

I've fantasised a bit about moving to transforms in this library's DOM and React component implementations, and it seems to involve a bit more than it initially seems:

• Item heights aren't known before the items have been rendered, so it'll have to re-render twice rather than once as the user scrolls: first time to measure the newly-shown items' heights and second time to apply the calculated Y positions of those items.

• A bit more complexity is added when one recalls that this library supports multi-column layout: now not only y positions but also x positions of every item would have to be calculated, and not only vertical spacing but also horizontal spacing between the items in a row.

• The state would have to include a new property — itemPositions — that would include an x and y position for every item.

• Using x/y positions for every item would mean that the x/y position of every item would no longer be dynamically calculated by a web browser (in auto mode) and instead would have to be pre-calculated by the library meaning that everything would have to be constantly re-calculated and re-rendered as the user resizes the window, not just on window resize end like it currently does. For example, if the user starts shrinking window width, the items' heights would start increasing due to content overflow, which, without constant re-calculation and re-rendering, would result in items being rendered on top of each other. So the fix for that would be re-calculating and re-rendering stuff immediately on every window resize event as the user drags the handle rather than waiting for the user to let go of that handle and stop resizing the window, which would obviously come with some performance penalties but maybe a modern device can handle such things without breaking a sweat.

The points listed above aren't something difficult to implement, it's just that I don't want to do it unless there're any real observed performance issues related to the "reflows" during scrolling. "If it works, no need to change it".