feat(react-virtualizer): Add improved scrollTo with iterative corrections for dynamic lists

[dmytrokirpa]

Description

This PR introduces an improved scrollTo implementation for VirtualizerScrollViewDynamic that handles dynamically sized items more accurately. The new behavior is opt-in via the enableScrollToCorrections prop to ensure backward compatibility.

Problem

When using scrollTo with dynamically sized items in virtualized lists, the target element could end up misaligned or outside the viewport because:

• Initial scroll position is calculated using estimated item sizes
• Items may resize after rendering (e.g., images loading, content expanding)
• The original implementation had no mechanism to correct for these size changes

Current behavior: The scrollTo function does not navigate to the correct position.

https://microsoft.github.io/fluentui-contrib/react-virtualizer/?path=/story/packages-react-virtualizer-virtualizerscrollviewdynamic--scroll-to

Screen.Recording.2025-12-03.at.16.13.00.mov

Solution

Added a new useScrollToItemDynamic hook that provides:

• Iterative corrections: Automatically adjusts scroll position as items are measured
• Smooth scrolling support: Allows smooth scroll animation followed by instant corrections
• Stability checks: Ensures the target element remains properly aligned before completing
• User scroll detection: Cancels the operation if the user manually scrolls

Screen.Recording.2025-12-03.at.16.14.41.mov

Changes

New Files

• packages/react-virtualizer/src/hooks/useScrollToItemDynamic.ts - New hook for managing scroll-to operations with corrections

Modified Files

• packages/react-virtualizer/src/hooks/useMeasureList.ts - Added onItemMeasured callback parameter
• packages/react-virtualizer/src/components/VirtualizerScrollViewDynamic/useVirtualizerScrollViewDynamic.tsx - Integrated new hook with opt-in behavior
• packages/react-virtualizer/src/components/VirtualizerScrollViewDynamic/VirtualizerScrollViewDynamic.types.ts - Added enableScrollToCorrections prop
• packages/react-virtualizer/stories/VirtualizerScrollViewDynamic/ScrollTo.stories.tsx - Updated story to demonstrate new behavior

Usage

<VirtualizerScrollViewDynamic
  numItems={1000}
  itemSize={100}
  getItemSize={getItemSizeCallback}
  imperativeRef={scrollRef}
  enableScrollToCorrections // opt-in to new behavior
>
  {(index) => <DynamicItem index={index} />}
</VirtualizerScrollViewDynamic>

// Smooth scrolling now works correctly with dynamic items
scrollRef.current?.scrollTo(500, 'smooth', (index) => {
  console.log(`Reached item ${index}`);
});

API

New Prop: enableScrollToCorrections

Prop	Type	Default	Description
enableScrollToCorrections	boolean	false	Enables improved scrollTo behavior with iterative corrections for dynamic content

When disabled (default): Uses legacy scrollToItemDynamic - existing behavior unchanged.

When enabled: Uses useScrollToItemDynamic hook which provides:

• Smooth scrolling with automatic position correction after animation
• Iterative corrections to handle dynamically sized items
• Temporarily disables useMeasureList scroll compensation during operations

Testing

• Tested with variable height items (random heights between 42-292px)
• Verified smooth scrolling works correctly with delayed corrections
• Confirmed legacy behavior is preserved when enableScrollToCorrections is not set

Open questions

Should we mark the existing scrollToDynamicItem util as deprecated (as we can't fix it or just remove)?

[Mitch-At-Work]

I'd vote we can remove the old functionality since we're still in zero dot, once we can finalize the dynamic behavior we should be ready to move to 1.0 and stabilize the API without retaining deprecated functionality.

[Mitch-At-Work]

Looks good, I don't see any cause for concern in regards to Virtualizer recalcs and functionality works as expected - I do think we should remove the old API and enable this by default as we are still in preview (0.x.y) but will leave that up to you