@legendapp/list 3.3.7 → 3.3.9

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 3.3.9
+
+- Fix: Rows after an item that changes size stay in the correct positions while scrolling
+
+## 3.3.8
+
+- Feat: Add `experimental_hideItemsUntilMeasured` to make items never display at provisional layouts and wait for correct sizing, at the cost of an extra render per recycled row. This fixes cases where slow item renders could display with gaps/overlaps when scrolling up quickly on slow phones.
+
 ## 3.3.7
 
 - Fix: Recycled rows no longer briefly show content from the wrong item when data is prepended.

package/animated.d.ts

@@ -8,7 +8,7 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerPosition${number}` | `containerSticky${number}`;
+type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
 type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
@@ -47,6 +47,8 @@ type ListenerTypeValueMap = {
     adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
+} & {
+    [K in ListenerType as K extends `containerLayoutReady${number}` ? K : never]: boolean;
 } & {
     [K in ListenerType as K extends `containerItemData${number}` ? K : never]: any;
 } & {
@@ -348,6 +350,20 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Configures the adaptive render signal. Items can use this to render a lighter version while scrolling quickly.
      */
     experimental_adaptiveRender?: AdaptiveRenderConfig;
+    /**
+     * Keeps a newly recycled item laid out but invisible until its size has been measured, so it is never painted at
+     * the estimated position it was recycled to. Only applies on the new architecture.
+     *
+     * This trades a possible flash at the wrong position for an extra render and native commit per recycled row, so it
+     * is worth enabling only for lists with dynamically sized items whose estimates are visibly wrong. Items with a
+     * size from `getFixedItemSize`, or with an already measured size, are exact and render immediately either way.
+     *
+     * Sticky headers are intentionally excluded. They are painted from a scroll-driven interpolation rather than the
+     * committed position, so hiding them would blink a header out mid-scroll without preventing a flash.
+     *
+     * @default false
+     */
+    experimental_hideItemsUntilMeasured?: boolean;
     /**
      * Function to call when the user pulls to refresh.
      */

package/keyboard-legacy.d.ts

@@ -9,7 +9,7 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerPosition${number}` | `containerSticky${number}`;
+type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
 type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
@@ -48,6 +48,8 @@ type ListenerTypeValueMap = {
     adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
+} & {
+    [K in ListenerType as K extends `containerLayoutReady${number}` ? K : never]: boolean;
 } & {
     [K in ListenerType as K extends `containerItemData${number}` ? K : never]: any;
 } & {

package/keyboard.d.ts

@@ -10,7 +10,7 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerPosition${number}` | `containerSticky${number}`;
+type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
 type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
@@ -49,6 +49,8 @@ type ListenerTypeValueMap = {
     adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
+} & {
+    [K in ListenerType as K extends `containerLayoutReady${number}` ? K : never]: boolean;
 } & {
     [K in ListenerType as K extends `containerItemData${number}` ? K : never]: any;
 } & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legendapp/list",
-  "version": "3.3.7",
+  "version": "3.3.9",
   "description": "Legend List is a drop-in replacement for FlatList with much better performance and supporting dynamically sized items.",
   "sideEffects": false,
   "private": false,

package/react-native.d.ts

@@ -8,7 +8,7 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerPosition${number}` | `containerSticky${number}`;
+type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
 type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
@@ -47,6 +47,8 @@ type ListenerTypeValueMap = {
     adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
+} & {
+    [K in ListenerType as K extends `containerLayoutReady${number}` ? K : never]: boolean;
 } & {
     [K in ListenerType as K extends `containerItemData${number}` ? K : never]: any;
 } & {
@@ -348,6 +350,20 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Configures the adaptive render signal. Items can use this to render a lighter version while scrolling quickly.
      */
     experimental_adaptiveRender?: AdaptiveRenderConfig;
+    /**
+     * Keeps a newly recycled item laid out but invisible until its size has been measured, so it is never painted at
+     * the estimated position it was recycled to. Only applies on the new architecture.
+     *
+     * This trades a possible flash at the wrong position for an extra render and native commit per recycled row, so it
+     * is worth enabling only for lists with dynamically sized items whose estimates are visibly wrong. Items with a
+     * size from `getFixedItemSize`, or with an already measured size, are exact and render immediately either way.
+     *
+     * Sticky headers are intentionally excluded. They are painted from a scroll-driven interpolation rather than the
+     * committed position, so hiding them would blink a header out mid-scroll without preventing a flash.
+     *
+     * @default false
+     */
+    experimental_hideItemsUntilMeasured?: boolean;
     /**
      * Function to call when the user pulls to refresh.
      */

package/react-native.js

@@ -4391,7 +4391,9 @@ function calculateItemsInView(ctx, params = {}) {
     const optimizeForVisibleWindow = !forceFullItemPositions && !dataChanged && numColumns > 1 && minIndexSizeChanged !== void 0;
     updateItemPositions(ctx, dataChanged, {
       doMVCP,
-      forceFullUpdate: !!forceFullItemPositions,
+      // A changed size shifts every following position. The scrolling early-exit
+      // would leave the untouched suffix in the old coordinate space.
+      forceFullUpdate: !!forceFullItemPositions || minIndexSizeChanged !== void 0,
       optimizeForVisibleWindow,
       scrollBottomBuffered,
       scrollVelocity: speed,
@@ -4596,15 +4598,19 @@ function calculateItemsInView(ctx, params = {}) {
           if (oldKey && oldKey !== id) {
             containerItemKeys.delete(oldKey);
           }
+          state.containerItemMetadata.set(
+            containerIndex,
+            createContainerItemMetadata(state, i, data[i], allocation.itemType)
+          );
           if (oldKey !== id) {
             changedContainerIds != null ? changedContainerIds : changedContainerIds = /* @__PURE__ */ new Set();
             changedContainerIds.add(containerIndex);
             state.containerItemGenerations[containerIndex] = ((_p = state.containerItemGenerations[containerIndex]) != null ? _p : 0) + 1;
+            if (state.props.hideItemsUntilMeasured) {
+              const isLayoutReady = state.sizesKnown.has(id) || resolveContainerItemMetadata(state, containerIndex, i, data[i]).fixedItemSize !== void 0;
+              set$(ctx, `containerLayoutReady${containerIndex}`, isLayoutReady);
+            }
           }
-          state.containerItemMetadata.set(
-            containerIndex,
-            createContainerItemMetadata(state, i, data[i], allocation.itemType)
-          );
           set$(ctx, `containerItemKey${containerIndex}`, id);
           set$(ctx, `containerItemIndex${containerIndex}`, i);
           set$(ctx, `containerItemData${containerIndex}`, data[i]);
@@ -5036,24 +5042,39 @@ function resolveSkippedAnchorReset(ctx, itemKey) {
     state.userScrollAnchorReset = void 0;
   }
 }
+function revealMeasuredGeneration(ctx, containerId, itemKey, generation) {
+  var _a3;
+  if (!ctx.state.props.hideItemsUntilMeasured) {
+    return;
+  }
+  const isCurrentGeneration = ((_a3 = ctx.state.containerItemGenerations[containerId]) != null ? _a3 : 0) === generation;
+  const isCurrentAssignment = peek$(ctx, `containerItemKey${containerId}`) === itemKey;
+  if (isCurrentGeneration && isCurrentAssignment) {
+    set$(ctx, `containerLayoutReady${containerId}`, true);
+  }
+}
 function measureContainersInLayoutEffect(ctx, targetContainerIds = null) {
-  var _a3, _b, _c;
+  var _a3, _b;
   const state = ctx.state;
   const measurements = [];
+  const measuredGenerations = state.props.hideItemsUntilMeasured ? [] : void 0;
   let isCollectingSynchronousMeasurements = true;
   const containerIds = targetContainerIds != null ? targetContainerIds : ctx.viewRefs.keys();
   for (const containerId of containerIds) {
-    const viewRef = ctx.viewRefs.get(containerId);
+    const view = (_a3 = ctx.viewRefs.get(containerId)) == null ? void 0 : _a3.current;
     const itemKey = peek$(ctx, `containerItemKey${containerId}`);
     if (itemKey !== void 0) {
-      const generation = ((_a3 = state.containerItemGenerations[containerId]) != null ? _a3 : 0) + 1;
+      const generation = ((_b = state.containerItemGenerations[containerId]) != null ? _b : 0) + 1;
       state.containerItemGenerations[containerId] = generation;
       const fixedItemSize = resolveFixedItemSize(ctx, containerId, itemKey);
       const canSkipMeasurement = !state.needsOtherAxisSize && fixedItemSize !== void 0 && state.sizesKnown.get(itemKey) === fixedItemSize + ctx.scrollAxisGap;
       if (canSkipMeasurement) {
         resolveSkippedAnchorReset(ctx, itemKey);
-      } else if (viewRef) {
-        (_c = (_b = viewRef.current) == null ? void 0 : _b.measure) == null ? void 0 : _c.call(_b, (_x, _y, width, height) => {
+        if (measuredGenerations) {
+          revealMeasuredGeneration(ctx, containerId, itemKey, generation);
+        }
+      } else if (view == null ? void 0 : view.measure) {
+        view.measure((_x, _y, width, height) => {
           var _a4;
           const isCurrentGeneration = ((_a4 = ctx.state.containerItemGenerations[containerId]) != null ? _a4 : 0) === generation;
           if (isCurrentGeneration) {
@@ -5064,17 +5085,28 @@ function measureContainersInLayoutEffect(ctx, targetContainerIds = null) {
             };
             if (isCollectingSynchronousMeasurements) {
               measurements.push(measurement);
+              measuredGenerations == null ? void 0 : measuredGenerations.push({ containerId, generation, itemKey });
             } else {
               updateItemSizes(ctx, measurement);
+              if (measuredGenerations) {
+                revealMeasuredGeneration(ctx, containerId, itemKey, generation);
+              }
             }
           }
         });
+      } else if (measuredGenerations) {
+        revealMeasuredGeneration(ctx, containerId, itemKey, generation);
       }
     }
   }
   isCollectingSynchronousMeasurements = false;
   if (measurements.length > 0) {
     updateItemSizesBatch(ctx, measurements);
+    if (measuredGenerations) {
+      for (const { containerId, generation, itemKey } of measuredGenerations) {
+        revealMeasuredGeneration(ctx, containerId, itemKey, generation);
+      }
+    }
   }
 }
 var typedForwardRef = React2__namespace.forwardRef;
@@ -5162,8 +5194,20 @@ var PositionViewState = typedMemo(function PositionViewState2({
   refView,
   ...rest
 }) {
-  const [position = POSITION_OUT_OF_VIEW, _itemKey] = useArr$([`containerPosition${id}`, `containerItemKey${id}`]);
-  return /* @__PURE__ */ React2__namespace.createElement(ReactNative.View, { ref: refView, style: [style, horizontal ? { left: position } : { top: position }], ...rest });
+  const [position = POSITION_OUT_OF_VIEW, _itemKey, layoutReady = true] = useArr$([
+    `containerPosition${id}`,
+    `containerItemKey${id}`,
+    `containerLayoutReady${id}`
+  ]);
+  return /* @__PURE__ */ React2__namespace.createElement(
+    ReactNative.View,
+    {
+      ref: refView,
+      style: [style, horizontal ? { left: position } : { top: position }, !layoutReady && { opacity: 0 }],
+      ...rest,
+      pointerEvents: layoutReady ? void 0 : "none"
+    }
+  );
 });
 var PositionViewAnimated = typedMemo(function PositionViewAnimated2({
   id,
@@ -6291,6 +6335,16 @@ function checkStructuralDataChange(state, dataProp, previousData) {
   return false;
 }
 
+// src/core/containerLayoutReady.ts
+var CONTAINER_LAYOUT_READY_PREFIX = "containerLayoutReady";
+function resetContainerLayoutReady(ctx) {
+  for (const signalName of ctx.values.keys()) {
+    if (signalName.startsWith(CONTAINER_LAYOUT_READY_PREFIX)) {
+      set$(ctx, signalName, void 0);
+    }
+  }
+}
+
 // src/core/doInitialAllocateContainers.ts
 function doInitialAllocateContainers(ctx) {
   var _a3, _b;
@@ -7197,6 +7251,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     initialScrollIndex: initialScrollIndexProp,
     initialScrollOffset: initialScrollOffsetProp,
     experimental_adaptiveRender,
+    experimental_hideItemsUntilMeasured,
     itemsAreEqual,
     keyExtractor: keyExtractorProp,
     ListEmptyComponent,
@@ -7417,6 +7472,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   const state = refState.current;
   const isFirstLocal = state.isFirst;
   const previousAdaptiveRender = state.props.adaptiveRender;
+  const previousHideItemsUntilMeasured = state.props.hideItemsUntilMeasured;
   const previousNumColumnsProp = state.props.numColumns;
   const didScrollAxisGapChange = !isFirstLocal && ctx.scrollAxisGap !== nextScrollAxisGap;
   ctx.scrollAxisGap = nextScrollAxisGap;
@@ -7462,6 +7518,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     estimatedItemSize,
     getFixedItemSize: useWrapIfItem(getFixedItemSize),
     getItemType: useWrapIfItem(getItemType),
+    hideItemsUntilMeasured: experimental_hideItemsUntilMeasured,
     horizontal: !!horizontal,
     itemsAreEqual,
     keyExtractor: useWrapIfItem(keyExtractor),
@@ -7499,6 +7556,9 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   if (!isFirstLocal && previousAdaptiveRender && !experimental_adaptiveRender) {
     resetAdaptiveRender(ctx);
   }
+  if (!isFirstLocal && previousHideItemsUntilMeasured && !experimental_hideItemsUntilMeasured) {
+    resetContainerLayoutReady(ctx);
+  }
   const memoizedLastItemKeys = React2.useMemo(() => {
     if (!dataProp.length) return [];
     return Array.from(

package/react-native.mjs

@@ -4370,7 +4370,9 @@ function calculateItemsInView(ctx, params = {}) {
     const optimizeForVisibleWindow = !forceFullItemPositions && !dataChanged && numColumns > 1 && minIndexSizeChanged !== void 0;
     updateItemPositions(ctx, dataChanged, {
       doMVCP,
-      forceFullUpdate: !!forceFullItemPositions,
+      // A changed size shifts every following position. The scrolling early-exit
+      // would leave the untouched suffix in the old coordinate space.
+      forceFullUpdate: !!forceFullItemPositions || minIndexSizeChanged !== void 0,
       optimizeForVisibleWindow,
       scrollBottomBuffered,
       scrollVelocity: speed,
@@ -4575,15 +4577,19 @@ function calculateItemsInView(ctx, params = {}) {
           if (oldKey && oldKey !== id) {
             containerItemKeys.delete(oldKey);
           }
+          state.containerItemMetadata.set(
+            containerIndex,
+            createContainerItemMetadata(state, i, data[i], allocation.itemType)
+          );
           if (oldKey !== id) {
             changedContainerIds != null ? changedContainerIds : changedContainerIds = /* @__PURE__ */ new Set();
             changedContainerIds.add(containerIndex);
             state.containerItemGenerations[containerIndex] = ((_p = state.containerItemGenerations[containerIndex]) != null ? _p : 0) + 1;
+            if (state.props.hideItemsUntilMeasured) {
+              const isLayoutReady = state.sizesKnown.has(id) || resolveContainerItemMetadata(state, containerIndex, i, data[i]).fixedItemSize !== void 0;
+              set$(ctx, `containerLayoutReady${containerIndex}`, isLayoutReady);
+            }
           }
-          state.containerItemMetadata.set(
-            containerIndex,
-            createContainerItemMetadata(state, i, data[i], allocation.itemType)
-          );
           set$(ctx, `containerItemKey${containerIndex}`, id);
           set$(ctx, `containerItemIndex${containerIndex}`, i);
           set$(ctx, `containerItemData${containerIndex}`, data[i]);
@@ -5015,24 +5021,39 @@ function resolveSkippedAnchorReset(ctx, itemKey) {
     state.userScrollAnchorReset = void 0;
   }
 }
+function revealMeasuredGeneration(ctx, containerId, itemKey, generation) {
+  var _a3;
+  if (!ctx.state.props.hideItemsUntilMeasured) {
+    return;
+  }
+  const isCurrentGeneration = ((_a3 = ctx.state.containerItemGenerations[containerId]) != null ? _a3 : 0) === generation;
+  const isCurrentAssignment = peek$(ctx, `containerItemKey${containerId}`) === itemKey;
+  if (isCurrentGeneration && isCurrentAssignment) {
+    set$(ctx, `containerLayoutReady${containerId}`, true);
+  }
+}
 function measureContainersInLayoutEffect(ctx, targetContainerIds = null) {
-  var _a3, _b, _c;
+  var _a3, _b;
   const state = ctx.state;
   const measurements = [];
+  const measuredGenerations = state.props.hideItemsUntilMeasured ? [] : void 0;
   let isCollectingSynchronousMeasurements = true;
   const containerIds = targetContainerIds != null ? targetContainerIds : ctx.viewRefs.keys();
   for (const containerId of containerIds) {
-    const viewRef = ctx.viewRefs.get(containerId);
+    const view = (_a3 = ctx.viewRefs.get(containerId)) == null ? void 0 : _a3.current;
     const itemKey = peek$(ctx, `containerItemKey${containerId}`);
     if (itemKey !== void 0) {
-      const generation = ((_a3 = state.containerItemGenerations[containerId]) != null ? _a3 : 0) + 1;
+      const generation = ((_b = state.containerItemGenerations[containerId]) != null ? _b : 0) + 1;
       state.containerItemGenerations[containerId] = generation;
       const fixedItemSize = resolveFixedItemSize(ctx, containerId, itemKey);
       const canSkipMeasurement = !state.needsOtherAxisSize && fixedItemSize !== void 0 && state.sizesKnown.get(itemKey) === fixedItemSize + ctx.scrollAxisGap;
       if (canSkipMeasurement) {
         resolveSkippedAnchorReset(ctx, itemKey);
-      } else if (viewRef) {
-        (_c = (_b = viewRef.current) == null ? void 0 : _b.measure) == null ? void 0 : _c.call(_b, (_x, _y, width, height) => {
+        if (measuredGenerations) {
+          revealMeasuredGeneration(ctx, containerId, itemKey, generation);
+        }
+      } else if (view == null ? void 0 : view.measure) {
+        view.measure((_x, _y, width, height) => {
           var _a4;
           const isCurrentGeneration = ((_a4 = ctx.state.containerItemGenerations[containerId]) != null ? _a4 : 0) === generation;
           if (isCurrentGeneration) {
@@ -5043,17 +5064,28 @@ function measureContainersInLayoutEffect(ctx, targetContainerIds = null) {
             };
             if (isCollectingSynchronousMeasurements) {
               measurements.push(measurement);
+              measuredGenerations == null ? void 0 : measuredGenerations.push({ containerId, generation, itemKey });
             } else {
               updateItemSizes(ctx, measurement);
+              if (measuredGenerations) {
+                revealMeasuredGeneration(ctx, containerId, itemKey, generation);
+              }
             }
           }
         });
+      } else if (measuredGenerations) {
+        revealMeasuredGeneration(ctx, containerId, itemKey, generation);
       }
     }
   }
   isCollectingSynchronousMeasurements = false;
   if (measurements.length > 0) {
     updateItemSizesBatch(ctx, measurements);
+    if (measuredGenerations) {
+      for (const { containerId, generation, itemKey } of measuredGenerations) {
+        revealMeasuredGeneration(ctx, containerId, itemKey, generation);
+      }
+    }
   }
 }
 var typedForwardRef = React2.forwardRef;
@@ -5141,8 +5173,20 @@ var PositionViewState = typedMemo(function PositionViewState2({
   refView,
   ...rest
 }) {
-  const [position = POSITION_OUT_OF_VIEW, _itemKey] = useArr$([`containerPosition${id}`, `containerItemKey${id}`]);
-  return /* @__PURE__ */ React2.createElement(View$1, { ref: refView, style: [style, horizontal ? { left: position } : { top: position }], ...rest });
+  const [position = POSITION_OUT_OF_VIEW, _itemKey, layoutReady = true] = useArr$([
+    `containerPosition${id}`,
+    `containerItemKey${id}`,
+    `containerLayoutReady${id}`
+  ]);
+  return /* @__PURE__ */ React2.createElement(
+    View$1,
+    {
+      ref: refView,
+      style: [style, horizontal ? { left: position } : { top: position }, !layoutReady && { opacity: 0 }],
+      ...rest,
+      pointerEvents: layoutReady ? void 0 : "none"
+    }
+  );
 });
 var PositionViewAnimated = typedMemo(function PositionViewAnimated2({
   id,
@@ -6270,6 +6314,16 @@ function checkStructuralDataChange(state, dataProp, previousData) {
   return false;
 }
 
+// src/core/containerLayoutReady.ts
+var CONTAINER_LAYOUT_READY_PREFIX = "containerLayoutReady";
+function resetContainerLayoutReady(ctx) {
+  for (const signalName of ctx.values.keys()) {
+    if (signalName.startsWith(CONTAINER_LAYOUT_READY_PREFIX)) {
+      set$(ctx, signalName, void 0);
+    }
+  }
+}
+
 // src/core/doInitialAllocateContainers.ts
 function doInitialAllocateContainers(ctx) {
   var _a3, _b;
@@ -7176,6 +7230,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     initialScrollIndex: initialScrollIndexProp,
     initialScrollOffset: initialScrollOffsetProp,
     experimental_adaptiveRender,
+    experimental_hideItemsUntilMeasured,
     itemsAreEqual,
     keyExtractor: keyExtractorProp,
     ListEmptyComponent,
@@ -7396,6 +7451,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   const state = refState.current;
   const isFirstLocal = state.isFirst;
   const previousAdaptiveRender = state.props.adaptiveRender;
+  const previousHideItemsUntilMeasured = state.props.hideItemsUntilMeasured;
   const previousNumColumnsProp = state.props.numColumns;
   const didScrollAxisGapChange = !isFirstLocal && ctx.scrollAxisGap !== nextScrollAxisGap;
   ctx.scrollAxisGap = nextScrollAxisGap;
@@ -7441,6 +7497,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     estimatedItemSize,
     getFixedItemSize: useWrapIfItem(getFixedItemSize),
     getItemType: useWrapIfItem(getItemType),
+    hideItemsUntilMeasured: experimental_hideItemsUntilMeasured,
     horizontal: !!horizontal,
     itemsAreEqual,
     keyExtractor: useWrapIfItem(keyExtractor),
@@ -7478,6 +7535,9 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   if (!isFirstLocal && previousAdaptiveRender && !experimental_adaptiveRender) {
     resetAdaptiveRender(ctx);
   }
+  if (!isFirstLocal && previousHideItemsUntilMeasured && !experimental_hideItemsUntilMeasured) {
+    resetContainerLayoutReady(ctx);
+  }
   const memoizedLastItemKeys = useMemo(() => {
     if (!dataProp.length) return [];
     return Array.from(

package/react-native.web.d.ts

@@ -31,7 +31,7 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerPosition${number}` | `containerSticky${number}`;
+type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
 type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
@@ -70,6 +70,8 @@ type ListenerTypeValueMap = {
     adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
+} & {
+    [K in ListenerType as K extends `containerLayoutReady${number}` ? K : never]: boolean;
 } & {
     [K in ListenerType as K extends `containerItemData${number}` ? K : never]: any;
 } & {
@@ -371,6 +373,20 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Configures the adaptive render signal. Items can use this to render a lighter version while scrolling quickly.
      */
     experimental_adaptiveRender?: AdaptiveRenderConfig;
+    /**
+     * Keeps a newly recycled item laid out but invisible until its size has been measured, so it is never painted at
+     * the estimated position it was recycled to. Only applies on the new architecture.
+     *
+     * This trades a possible flash at the wrong position for an extra render and native commit per recycled row, so it
+     * is worth enabling only for lists with dynamically sized items whose estimates are visibly wrong. Items with a
+     * size from `getFixedItemSize`, or with an already measured size, are exact and render immediately either way.
+     *
+     * Sticky headers are intentionally excluded. They are painted from a scroll-driven interpolation rather than the
+     * committed position, so hiding them would blink a header out mid-scroll without preventing a flash.
+     *
+     * @default false
+     */
+    experimental_hideItemsUntilMeasured?: boolean;
     /**
      * Function to call when the user pulls to refresh.
      */

package/react-native.web.js

@@ -4420,7 +4420,9 @@ function calculateItemsInView(ctx, params = {}) {
     const optimizeForVisibleWindow = !forceFullItemPositions && !dataChanged && numColumns > 1 && minIndexSizeChanged !== void 0;
     updateItemPositions(ctx, dataChanged, {
       doMVCP,
-      forceFullUpdate: !!forceFullItemPositions,
+      // A changed size shifts every following position. The scrolling early-exit
+      // would leave the untouched suffix in the old coordinate space.
+      forceFullUpdate: !!forceFullItemPositions || minIndexSizeChanged !== void 0,
       optimizeForVisibleWindow,
       scrollBottomBuffered,
       scrollVelocity: speed,
@@ -4625,15 +4627,19 @@ function calculateItemsInView(ctx, params = {}) {
           if (oldKey && oldKey !== id) {
             containerItemKeys.delete(oldKey);
           }
+          state.containerItemMetadata.set(
+            containerIndex,
+            createContainerItemMetadata(state, i, data[i], allocation.itemType)
+          );
           if (oldKey !== id) {
             changedContainerIds != null ? changedContainerIds : changedContainerIds = /* @__PURE__ */ new Set();
             changedContainerIds.add(containerIndex);
             state.containerItemGenerations[containerIndex] = ((_p = state.containerItemGenerations[containerIndex]) != null ? _p : 0) + 1;
+            if (state.props.hideItemsUntilMeasured) {
+              const isLayoutReady = state.sizesKnown.has(id) || resolveContainerItemMetadata(state, containerIndex, i, data[i]).fixedItemSize !== void 0;
+              set$(ctx, `containerLayoutReady${containerIndex}`, isLayoutReady);
+            }
           }
-          state.containerItemMetadata.set(
-            containerIndex,
-            createContainerItemMetadata(state, i, data[i], allocation.itemType)
-          );
           set$(ctx, `containerItemKey${containerIndex}`, id);
           set$(ctx, `containerItemIndex${containerIndex}`, i);
           set$(ctx, `containerItemData${containerIndex}`, data[i]);
@@ -6950,6 +6956,16 @@ function checkStructuralDataChange(state, dataProp, previousData) {
   return false;
 }
 
+// src/core/containerLayoutReady.ts
+var CONTAINER_LAYOUT_READY_PREFIX = "containerLayoutReady";
+function resetContainerLayoutReady(ctx) {
+  for (const signalName of ctx.values.keys()) {
+    if (signalName.startsWith(CONTAINER_LAYOUT_READY_PREFIX)) {
+      set$(ctx, signalName, void 0);
+    }
+  }
+}
+
 // src/core/doInitialAllocateContainers.ts
 function doInitialAllocateContainers(ctx) {
   var _a3, _b;
@@ -7840,6 +7856,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     initialScrollIndex: initialScrollIndexProp,
     initialScrollOffset: initialScrollOffsetProp,
     experimental_adaptiveRender,
+    experimental_hideItemsUntilMeasured,
     itemsAreEqual,
     keyExtractor: keyExtractorProp,
     ListEmptyComponent,
@@ -8060,6 +8077,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   const state = refState.current;
   const isFirstLocal = state.isFirst;
   const previousAdaptiveRender = state.props.adaptiveRender;
+  const previousHideItemsUntilMeasured = state.props.hideItemsUntilMeasured;
   const previousNumColumnsProp = state.props.numColumns;
   const didScrollAxisGapChange = !isFirstLocal && ctx.scrollAxisGap !== nextScrollAxisGap;
   ctx.scrollAxisGap = nextScrollAxisGap;
@@ -8105,6 +8123,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     estimatedItemSize,
     getFixedItemSize: useWrapIfItem(getFixedItemSize),
     getItemType: useWrapIfItem(getItemType),
+    hideItemsUntilMeasured: experimental_hideItemsUntilMeasured,
     horizontal: !!horizontal,
     itemsAreEqual,
     keyExtractor: useWrapIfItem(keyExtractor),
@@ -8142,6 +8161,9 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   if (!isFirstLocal && previousAdaptiveRender && !experimental_adaptiveRender) {
     resetAdaptiveRender(ctx);
   }
+  if (!isFirstLocal && previousHideItemsUntilMeasured && !experimental_hideItemsUntilMeasured) {
+    resetContainerLayoutReady(ctx);
+  }
   const memoizedLastItemKeys = React3.useMemo(() => {
     if (!dataProp.length) return [];
     return Array.from(

package/react-native.web.mjs

@@ -4399,7 +4399,9 @@ function calculateItemsInView(ctx, params = {}) {
     const optimizeForVisibleWindow = !forceFullItemPositions && !dataChanged && numColumns > 1 && minIndexSizeChanged !== void 0;
     updateItemPositions(ctx, dataChanged, {
       doMVCP,
-      forceFullUpdate: !!forceFullItemPositions,
+      // A changed size shifts every following position. The scrolling early-exit
+      // would leave the untouched suffix in the old coordinate space.
+      forceFullUpdate: !!forceFullItemPositions || minIndexSizeChanged !== void 0,
       optimizeForVisibleWindow,
       scrollBottomBuffered,
       scrollVelocity: speed,
@@ -4604,15 +4606,19 @@ function calculateItemsInView(ctx, params = {}) {
           if (oldKey && oldKey !== id) {
             containerItemKeys.delete(oldKey);
           }
+          state.containerItemMetadata.set(
+            containerIndex,
+            createContainerItemMetadata(state, i, data[i], allocation.itemType)
+          );
           if (oldKey !== id) {
             changedContainerIds != null ? changedContainerIds : changedContainerIds = /* @__PURE__ */ new Set();
             changedContainerIds.add(containerIndex);
             state.containerItemGenerations[containerIndex] = ((_p = state.containerItemGenerations[containerIndex]) != null ? _p : 0) + 1;
+            if (state.props.hideItemsUntilMeasured) {
+              const isLayoutReady = state.sizesKnown.has(id) || resolveContainerItemMetadata(state, containerIndex, i, data[i]).fixedItemSize !== void 0;
+              set$(ctx, `containerLayoutReady${containerIndex}`, isLayoutReady);
+            }
           }
-          state.containerItemMetadata.set(
-            containerIndex,
-            createContainerItemMetadata(state, i, data[i], allocation.itemType)
-          );
           set$(ctx, `containerItemKey${containerIndex}`, id);
           set$(ctx, `containerItemIndex${containerIndex}`, i);
           set$(ctx, `containerItemData${containerIndex}`, data[i]);
@@ -6929,6 +6935,16 @@ function checkStructuralDataChange(state, dataProp, previousData) {
   return false;
 }
 
+// src/core/containerLayoutReady.ts
+var CONTAINER_LAYOUT_READY_PREFIX = "containerLayoutReady";
+function resetContainerLayoutReady(ctx) {
+  for (const signalName of ctx.values.keys()) {
+    if (signalName.startsWith(CONTAINER_LAYOUT_READY_PREFIX)) {
+      set$(ctx, signalName, void 0);
+    }
+  }
+}
+
 // src/core/doInitialAllocateContainers.ts
 function doInitialAllocateContainers(ctx) {
   var _a3, _b;
@@ -7819,6 +7835,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     initialScrollIndex: initialScrollIndexProp,
     initialScrollOffset: initialScrollOffsetProp,
     experimental_adaptiveRender,
+    experimental_hideItemsUntilMeasured,
     itemsAreEqual,
     keyExtractor: keyExtractorProp,
     ListEmptyComponent,
@@ -8039,6 +8056,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   const state = refState.current;
   const isFirstLocal = state.isFirst;
   const previousAdaptiveRender = state.props.adaptiveRender;
+  const previousHideItemsUntilMeasured = state.props.hideItemsUntilMeasured;
   const previousNumColumnsProp = state.props.numColumns;
   const didScrollAxisGapChange = !isFirstLocal && ctx.scrollAxisGap !== nextScrollAxisGap;
   ctx.scrollAxisGap = nextScrollAxisGap;
@@ -8084,6 +8102,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     estimatedItemSize,
     getFixedItemSize: useWrapIfItem(getFixedItemSize),
     getItemType: useWrapIfItem(getItemType),
+    hideItemsUntilMeasured: experimental_hideItemsUntilMeasured,
     horizontal: !!horizontal,
     itemsAreEqual,
     keyExtractor: useWrapIfItem(keyExtractor),
@@ -8121,6 +8140,9 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   if (!isFirstLocal && previousAdaptiveRender && !experimental_adaptiveRender) {
     resetAdaptiveRender(ctx);
   }
+  if (!isFirstLocal && previousHideItemsUntilMeasured && !experimental_hideItemsUntilMeasured) {
+    resetContainerLayoutReady(ctx);
+  }
   const memoizedLastItemKeys = useMemo(() => {
     if (!dataProp.length) return [];
     return Array.from(

package/react.d.ts

@@ -31,7 +31,7 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerPosition${number}` | `containerSticky${number}`;
+type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
 type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
@@ -70,6 +70,8 @@ type ListenerTypeValueMap = {
     adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
+} & {
+    [K in ListenerType as K extends `containerLayoutReady${number}` ? K : never]: boolean;
 } & {
     [K in ListenerType as K extends `containerItemData${number}` ? K : never]: any;
 } & {
@@ -371,6 +373,20 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Configures the adaptive render signal. Items can use this to render a lighter version while scrolling quickly.
      */
     experimental_adaptiveRender?: AdaptiveRenderConfig;
+    /**
+     * Keeps a newly recycled item laid out but invisible until its size has been measured, so it is never painted at
+     * the estimated position it was recycled to. Only applies on the new architecture.
+     *
+     * This trades a possible flash at the wrong position for an extra render and native commit per recycled row, so it
+     * is worth enabling only for lists with dynamically sized items whose estimates are visibly wrong. Items with a
+     * size from `getFixedItemSize`, or with an already measured size, are exact and render immediately either way.
+     *
+     * Sticky headers are intentionally excluded. They are painted from a scroll-driven interpolation rather than the
+     * committed position, so hiding them would blink a header out mid-scroll without preventing a flash.
+     *
+     * @default false
+     */
+    experimental_hideItemsUntilMeasured?: boolean;
     /**
      * Function to call when the user pulls to refresh.
      */

package/react.js

@@ -4420,7 +4420,9 @@ function calculateItemsInView(ctx, params = {}) {
     const optimizeForVisibleWindow = !forceFullItemPositions && !dataChanged && numColumns > 1 && minIndexSizeChanged !== void 0;
     updateItemPositions(ctx, dataChanged, {
       doMVCP,
-      forceFullUpdate: !!forceFullItemPositions,
+      // A changed size shifts every following position. The scrolling early-exit
+      // would leave the untouched suffix in the old coordinate space.
+      forceFullUpdate: !!forceFullItemPositions || minIndexSizeChanged !== void 0,
       optimizeForVisibleWindow,
       scrollBottomBuffered,
       scrollVelocity: speed,
@@ -4625,15 +4627,19 @@ function calculateItemsInView(ctx, params = {}) {
           if (oldKey && oldKey !== id) {
             containerItemKeys.delete(oldKey);
           }
+          state.containerItemMetadata.set(
+            containerIndex,
+            createContainerItemMetadata(state, i, data[i], allocation.itemType)
+          );
           if (oldKey !== id) {
             changedContainerIds != null ? changedContainerIds : changedContainerIds = /* @__PURE__ */ new Set();
             changedContainerIds.add(containerIndex);
             state.containerItemGenerations[containerIndex] = ((_p = state.containerItemGenerations[containerIndex]) != null ? _p : 0) + 1;
+            if (state.props.hideItemsUntilMeasured) {
+              const isLayoutReady = state.sizesKnown.has(id) || resolveContainerItemMetadata(state, containerIndex, i, data[i]).fixedItemSize !== void 0;
+              set$(ctx, `containerLayoutReady${containerIndex}`, isLayoutReady);
+            }
           }
-          state.containerItemMetadata.set(
-            containerIndex,
-            createContainerItemMetadata(state, i, data[i], allocation.itemType)
-          );
           set$(ctx, `containerItemKey${containerIndex}`, id);
           set$(ctx, `containerItemIndex${containerIndex}`, i);
           set$(ctx, `containerItemData${containerIndex}`, data[i]);
@@ -6950,6 +6956,16 @@ function checkStructuralDataChange(state, dataProp, previousData) {
   return false;
 }
 
+// src/core/containerLayoutReady.ts
+var CONTAINER_LAYOUT_READY_PREFIX = "containerLayoutReady";
+function resetContainerLayoutReady(ctx) {
+  for (const signalName of ctx.values.keys()) {
+    if (signalName.startsWith(CONTAINER_LAYOUT_READY_PREFIX)) {
+      set$(ctx, signalName, void 0);
+    }
+  }
+}
+
 // src/core/doInitialAllocateContainers.ts
 function doInitialAllocateContainers(ctx) {
   var _a3, _b;
@@ -7840,6 +7856,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     initialScrollIndex: initialScrollIndexProp,
     initialScrollOffset: initialScrollOffsetProp,
     experimental_adaptiveRender,
+    experimental_hideItemsUntilMeasured,
     itemsAreEqual,
     keyExtractor: keyExtractorProp,
     ListEmptyComponent,
@@ -8060,6 +8077,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   const state = refState.current;
   const isFirstLocal = state.isFirst;
   const previousAdaptiveRender = state.props.adaptiveRender;
+  const previousHideItemsUntilMeasured = state.props.hideItemsUntilMeasured;
   const previousNumColumnsProp = state.props.numColumns;
   const didScrollAxisGapChange = !isFirstLocal && ctx.scrollAxisGap !== nextScrollAxisGap;
   ctx.scrollAxisGap = nextScrollAxisGap;
@@ -8105,6 +8123,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     estimatedItemSize,
     getFixedItemSize: useWrapIfItem(getFixedItemSize),
     getItemType: useWrapIfItem(getItemType),
+    hideItemsUntilMeasured: experimental_hideItemsUntilMeasured,
     horizontal: !!horizontal,
     itemsAreEqual,
     keyExtractor: useWrapIfItem(keyExtractor),
@@ -8142,6 +8161,9 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   if (!isFirstLocal && previousAdaptiveRender && !experimental_adaptiveRender) {
     resetAdaptiveRender(ctx);
   }
+  if (!isFirstLocal && previousHideItemsUntilMeasured && !experimental_hideItemsUntilMeasured) {
+    resetContainerLayoutReady(ctx);
+  }
   const memoizedLastItemKeys = React3.useMemo(() => {
     if (!dataProp.length) return [];
     return Array.from(

package/react.mjs

@@ -4399,7 +4399,9 @@ function calculateItemsInView(ctx, params = {}) {
     const optimizeForVisibleWindow = !forceFullItemPositions && !dataChanged && numColumns > 1 && minIndexSizeChanged !== void 0;
     updateItemPositions(ctx, dataChanged, {
       doMVCP,
-      forceFullUpdate: !!forceFullItemPositions,
+      // A changed size shifts every following position. The scrolling early-exit
+      // would leave the untouched suffix in the old coordinate space.
+      forceFullUpdate: !!forceFullItemPositions || minIndexSizeChanged !== void 0,
       optimizeForVisibleWindow,
       scrollBottomBuffered,
       scrollVelocity: speed,
@@ -4604,15 +4606,19 @@ function calculateItemsInView(ctx, params = {}) {
           if (oldKey && oldKey !== id) {
             containerItemKeys.delete(oldKey);
           }
+          state.containerItemMetadata.set(
+            containerIndex,
+            createContainerItemMetadata(state, i, data[i], allocation.itemType)
+          );
           if (oldKey !== id) {
             changedContainerIds != null ? changedContainerIds : changedContainerIds = /* @__PURE__ */ new Set();
             changedContainerIds.add(containerIndex);
             state.containerItemGenerations[containerIndex] = ((_p = state.containerItemGenerations[containerIndex]) != null ? _p : 0) + 1;
+            if (state.props.hideItemsUntilMeasured) {
+              const isLayoutReady = state.sizesKnown.has(id) || resolveContainerItemMetadata(state, containerIndex, i, data[i]).fixedItemSize !== void 0;
+              set$(ctx, `containerLayoutReady${containerIndex}`, isLayoutReady);
+            }
           }
-          state.containerItemMetadata.set(
-            containerIndex,
-            createContainerItemMetadata(state, i, data[i], allocation.itemType)
-          );
           set$(ctx, `containerItemKey${containerIndex}`, id);
           set$(ctx, `containerItemIndex${containerIndex}`, i);
           set$(ctx, `containerItemData${containerIndex}`, data[i]);
@@ -6929,6 +6935,16 @@ function checkStructuralDataChange(state, dataProp, previousData) {
   return false;
 }
 
+// src/core/containerLayoutReady.ts
+var CONTAINER_LAYOUT_READY_PREFIX = "containerLayoutReady";
+function resetContainerLayoutReady(ctx) {
+  for (const signalName of ctx.values.keys()) {
+    if (signalName.startsWith(CONTAINER_LAYOUT_READY_PREFIX)) {
+      set$(ctx, signalName, void 0);
+    }
+  }
+}
+
 // src/core/doInitialAllocateContainers.ts
 function doInitialAllocateContainers(ctx) {
   var _a3, _b;
@@ -7819,6 +7835,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     initialScrollIndex: initialScrollIndexProp,
     initialScrollOffset: initialScrollOffsetProp,
     experimental_adaptiveRender,
+    experimental_hideItemsUntilMeasured,
     itemsAreEqual,
     keyExtractor: keyExtractorProp,
     ListEmptyComponent,
@@ -8039,6 +8056,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   const state = refState.current;
   const isFirstLocal = state.isFirst;
   const previousAdaptiveRender = state.props.adaptiveRender;
+  const previousHideItemsUntilMeasured = state.props.hideItemsUntilMeasured;
   const previousNumColumnsProp = state.props.numColumns;
   const didScrollAxisGapChange = !isFirstLocal && ctx.scrollAxisGap !== nextScrollAxisGap;
   ctx.scrollAxisGap = nextScrollAxisGap;
@@ -8084,6 +8102,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     estimatedItemSize,
     getFixedItemSize: useWrapIfItem(getFixedItemSize),
     getItemType: useWrapIfItem(getItemType),
+    hideItemsUntilMeasured: experimental_hideItemsUntilMeasured,
     horizontal: !!horizontal,
     itemsAreEqual,
     keyExtractor: useWrapIfItem(keyExtractor),
@@ -8121,6 +8140,9 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   if (!isFirstLocal && previousAdaptiveRender && !experimental_adaptiveRender) {
     resetAdaptiveRender(ctx);
   }
+  if (!isFirstLocal && previousHideItemsUntilMeasured && !experimental_hideItemsUntilMeasured) {
+    resetContainerLayoutReady(ctx);
+  }
   const memoizedLastItemKeys = useMemo(() => {
     if (!dataProp.length) return [];
     return Array.from(

package/reanimated.d.ts

@@ -9,7 +9,7 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerPosition${number}` | `containerSticky${number}`;
+type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
 type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
@@ -48,6 +48,8 @@ type ListenerTypeValueMap = {
     adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
+} & {
+    [K in ListenerType as K extends `containerLayoutReady${number}` ? K : never]: boolean;
 } & {
     [K in ListenerType as K extends `containerItemData${number}` ? K : never]: any;
 } & {
@@ -349,6 +351,20 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Configures the adaptive render signal. Items can use this to render a lighter version while scrolling quickly.
      */
     experimental_adaptiveRender?: AdaptiveRenderConfig;
+    /**
+     * Keeps a newly recycled item laid out but invisible until its size has been measured, so it is never painted at
+     * the estimated position it was recycled to. Only applies on the new architecture.
+     *
+     * This trades a possible flash at the wrong position for an extra render and native commit per recycled row, so it
+     * is worth enabling only for lists with dynamically sized items whose estimates are visibly wrong. Items with a
+     * size from `getFixedItemSize`, or with an already measured size, are exact and render immediately either way.
+     *
+     * Sticky headers are intentionally excluded. They are painted from a scroll-driven interpolation rather than the
+     * committed position, so hiding them would blink a header out mid-scroll without preventing a flash.
+     *
+     * @default false
+     */
+    experimental_hideItemsUntilMeasured?: boolean;
     /**
      * Function to call when the user pulls to refresh.
      */

package/reanimated.js

@@ -113,7 +113,10 @@ var ReanimatedPositionViewSticky = typedMemo(function ReanimatedPositionViewStic
 var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(props) {
   const ctx = useStateContext();
   const { id, horizontal, style, refView, children, recycleItems, layoutTransition, ...rest } = props;
-  const [positionValue = POSITION_OUT_OF_VIEW] = useArr$([`containerPosition${id}`]);
+  const [positionValue = POSITION_OUT_OF_VIEW, layoutReady = true] = useArr$([
+    `containerPosition${id}`,
+    `containerLayoutReady${id}`
+  ]);
   const prevItemKeyRef = React__namespace.useRef(void 0);
   let shouldSkipTransitionForRecycleReuse = false;
   if (recycleItems && layoutTransition) {
@@ -127,8 +130,8 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
     prevItemKeyRef.current = void 0;
   }
   const viewStyle = React__namespace.useMemo(
-    () => [style, horizontal ? { left: positionValue } : { top: positionValue }],
-    [horizontal, positionValue, style]
+    () => [style, horizontal ? { left: positionValue } : { top: positionValue }, !layoutReady && { opacity: 0 }],
+    [horizontal, layoutReady, positionValue, style]
   );
   return /* @__PURE__ */ React__namespace.createElement(
     Reanimated__default.default.View,
@@ -136,7 +139,8 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
       layout: shouldSkipTransitionForRecycleReuse ? void 0 : layoutTransition,
       ref: refView,
       style: viewStyle,
-      ...rest
+      ...rest,
+      pointerEvents: layoutReady ? void 0 : "none"
     },
     children
   );

package/reanimated.mjs

@@ -89,7 +89,10 @@ var ReanimatedPositionViewSticky = typedMemo(function ReanimatedPositionViewStic
 var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(props) {
   const ctx = useStateContext();
   const { id, horizontal, style, refView, children, recycleItems, layoutTransition, ...rest } = props;
-  const [positionValue = POSITION_OUT_OF_VIEW] = useArr$([`containerPosition${id}`]);
+  const [positionValue = POSITION_OUT_OF_VIEW, layoutReady = true] = useArr$([
+    `containerPosition${id}`,
+    `containerLayoutReady${id}`
+  ]);
   const prevItemKeyRef = React.useRef(void 0);
   let shouldSkipTransitionForRecycleReuse = false;
   if (recycleItems && layoutTransition) {
@@ -103,8 +106,8 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
     prevItemKeyRef.current = void 0;
   }
   const viewStyle = React.useMemo(
-    () => [style, horizontal ? { left: positionValue } : { top: positionValue }],
-    [horizontal, positionValue, style]
+    () => [style, horizontal ? { left: positionValue } : { top: positionValue }, !layoutReady && { opacity: 0 }],
+    [horizontal, layoutReady, positionValue, style]
   );
   return /* @__PURE__ */ React.createElement(
     Reanimated.View,
@@ -112,7 +115,8 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
       layout: shouldSkipTransitionForRecycleReuse ? void 0 : layoutTransition,
       ref: refView,
       style: viewStyle,
-      ...rest
+      ...rest,
+      pointerEvents: layoutReady ? void 0 : "none"
     },
     children
   );

package/section-list.d.ts

@@ -65,7 +65,7 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerPosition${number}` | `containerSticky${number}`;
+type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
 type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
@@ -104,6 +104,8 @@ type ListenerTypeValueMap = {
     adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
+} & {
+    [K in ListenerType as K extends `containerLayoutReady${number}` ? K : never]: boolean;
 } & {
     [K in ListenerType as K extends `containerItemData${number}` ? K : never]: any;
 } & {
@@ -405,6 +407,20 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Configures the adaptive render signal. Items can use this to render a lighter version while scrolling quickly.
      */
     experimental_adaptiveRender?: AdaptiveRenderConfig;
+    /**
+     * Keeps a newly recycled item laid out but invisible until its size has been measured, so it is never painted at
+     * the estimated position it was recycled to. Only applies on the new architecture.
+     *
+     * This trades a possible flash at the wrong position for an extra render and native commit per recycled row, so it
+     * is worth enabling only for lists with dynamically sized items whose estimates are visibly wrong. Items with a
+     * size from `getFixedItemSize`, or with an already measured size, are exact and render immediately either way.
+     *
+     * Sticky headers are intentionally excluded. They are painted from a scroll-driven interpolation rather than the
+     * committed position, so hiding them would blink a header out mid-scroll without preventing a flash.
+     *
+     * @default false
+     */
+    experimental_hideItemsUntilMeasured?: boolean;
     /**
      * Function to call when the user pulls to refresh.
      */