[aehmt]

Bug

When initialItemCount exceeds data.length, buildListStateFromItemCount creates phantom items with data: undefined. These phantom items produce zero-height DOM elements, triggering the "Zero-sized element, this should not happen" console error for each one.

Reproduction

<Virtuoso
  data={["A", "B", "C"]}       // 3 items
  initialItemCount={10}          // greater than data.length
  itemContent={(index, item) => <div>{item ?? "undefined!"}</div>}
  style={{ height: 400 }}
/>

Console shows Zero-sized element, this should not happen {child: div} repeated 7 times (10 - 3 = 7 phantom items).

Root cause

In buildListStateFromItemCount (listStateSystem.ts), the item count is not clamped to the data array length:

const adjustedCount = itemCount + includedGroupsCount
// adjustedCount can exceed data.length ^^^
const items = Array.from({ length: adjustedCount }).map((_, index) => ({
    data: data[index + initialTopMostItemIndexNumber],
    // ^^^ accesses indices beyond data.length → undefined
    ...
}))

Fix

Clamp adjustedCount to data.length when the data prop is provided (non-empty array):

const adjustedCount = data.length > 0
  ? Math.min(itemCount + includedGroupsCount, data.length)
  : itemCount + includedGroupsCount

When data is not used (totalCount-only mode, where data defaults to []), the existing behavior is preserved.

Relation to #1060

This is a separate code path from the issue fixed in #1061. That PR addressed a ResizeObserver timing issue in useSize. This fix addresses buildListStateFromItemCount never clamping to data.length — a bug that was present before and after #1061. The continued reports on #1060 (e.g., this comment on v4.8.0+) suggest this code path was the remaining unfixed cause.

Test added

Added a test in listSystem.test.ts verifying that initialItemCount is clamped to data.length and no items have undefined data.

[changeset-bot]

🦋 Changeset detected

Latest commit: 797e7a5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
react-virtuoso	Patch
@virtuoso.dev/examples	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[petyosi]

This is technically a valid fix, but can you explain why would the library consumer pass such a value? As in, is this purely defensive improvement for an invalid value?

[aehmt]

This is technically a valid fix, but can you explain why would the library consumer pass such a value? As in, is this purely defensive improvement for an invalid value?

@petyosi It's not purely defensive, this is a natural mismatch that happens when initialItemCount is set to a fixed value to avoid the empty flash before Virtuoso measures the viewport. You don't always know how many items the server will return, you pick a generous number (e.g., 10) so the first paint isn't blank, but data may have fewer items:

<Virtuoso
  data={results}             // could be 3 items
  initialItemCount={10}      // generous default to fill viewport on first paint
  itemContent={(i, item) => <div>{item.name}</div>}
/>

This isn't an invalid value case, initialItemCount and data are independent props, and the library shouldn't produce phantom items with undefined data when one exceeds the other. Those phantom items render as zero-height DOM elements, which triggers the Zero-sized element, this should not happen console errors, noisy in production envoriments and confusing to debug. The clamp is a one line fix and preserves existing behavior when data isn't used (totalCount-only mode).

[helloworldcyj]

We pass initialItemCount={Math.min(3, data.length)}, so the prop is always in range. The problem:

1. In systemToComponent, props are published in the fixed key order of the optional map — data is published before initialItemCount. This happens both on mount and in the useLayoutEffect that re-publishes all props on every render.
2. In listStateSystem, initialItemCount is not part of the reactive combineLatest — it is read synchronously from its stateful cell inside the listState computation.
3. So on a render where data shrinks (3 → 2) and initialItemCount is lowered accordingly (3 → 2), publishing data first synchronously recomputes listState with the stale cell value (3) against the new, shorter data.
4. If visibleRange is still [0, 0], the computation takes the buildListStateFromItemCount branch and generates data[2] === undefined — a phantom item.

When does visibleRange stay [0, 0]? Viewport measurement is asynchronous (ResizeObserver + requestAnimationFrame) and skipped for hidden elements (offsetParent === null guards in both the RO wrapper and the custom-scroll-parent listener). If the component mounts or re-mounts while the page is hidden — in our case an Android WebView covered by another native screen — the measurement never runs and visibleRange keeps its initial [0, 0] until the page becomes visible again (same behavior noted in #970). Any data update landing in that window walks straight into the unclamped path.

Production trace of one crash: list renders 3 items (cell = 3) → user opens another native screen, webview hidden before measurement completes → a background refresh on page-show removes one item → the same render publishes data (2 items) then initialItemCount (2) → the data publish recomputes listState with the stale cell value 3 → phantom item at index 2 → computeItemKey(2, undefined) throws → blank page.

So the clamp in this PR is not defensive hardening for an invalid prop — it is the minimal invariant that makes the library's own one-publish-cycle staleness harmless. We would really appreciate it landing.

Two small notes on the patch itself (optional, not blocking):

• With initialTopMostItemIndex > 0, data[index + initialIndexNumber] can still overflow even after the length clamp; Math.min(adjustedCount, data.length - initialIndexNumber) would cover that case too.
• Alternatively, making initialItemCount part of the combineLatest (or publishing it before data) would eliminate the stale window entirely — but the clamp alone already prevents the crash.