[iOS/MacCatalyst] Fix CollectionView ScrollTo for horizontal layouts

[Shalini-Ashokan]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Issue Details

CollectionView’s programmatic ScrollTo does not work when using a horizontal ItemsLayout on iOS/MacCatalyst. After calling ScrollTo(index, position: ScrollToPosition.Start, animate: true), the scroll position remains unchanged.

Root Cause

In the CV2 iOS handler, the scroll direction is hardcoded to Vertical instead of using the actual layout direction. As a result, horizontal layouts receive incorrect scroll position calculations.

Description of Change

Replace the hardcoded vertical direction with a dynamic call that retrieves the actual scroll direction from the controller. This ensures that horizontal layouts receive the correct scroll position values.

Fix reference

I have fixed the issue in the same way as CV1, by referring to the following code.

maui/src/Controls/src/Core/Handlers/Items/ItemsViewHandler.iOS.cs

Line 110 in 52f9fc2

Controller.CollectionView.ScrollToItem(indexPath,

Validated the behavior in the following platforms

• Android
• Windows
• iOS
• Mac

Issues Fixed

Fixes #33852

Output ScreenShot

Before	After
Before-Fix.mov	After-Fix.mov

[dotnet-policy-service]

Hey there @@Shalini-Ashokan! Thank you so much for your PR! Someone from the team will get assigned to your PR shortly and we'll get it reviewed.

[sheiksyedm]

/azp run maui-pr-uitests 

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[rmarinho]

🤖 AI Summary

📊 Expand Full Review

---

🔍 Pre-Flight — Context & Validation

---

📝 Review Session — Fixed the collection view scroll to issue · 345ea8d

---

Issue: #33852 - [iOS/MacCatalyst] CollectionView ScrollTo does not work with horizontal Layout
Platforms Affected: iOS, MacCatalyst
Files Changed: 1 implementation file, 2 test files

Issue Summary

CollectionView's programmatic ScrollTo does not work when using a horizontal ItemsLayout on iOS/MacCatalyst. After calling ScrollTo(index, position: ScrollToPosition.Start, animate: true), the scroll position remains unchanged. This issue affects only the CV2 (CollectionView2) handler; CV1 works correctly.

Root Cause (from PR description)

In ItemsViewHandler2.iOS.cs, the scroll direction was hardcoded to UICollectionViewScrollDirection.Vertical. Horizontal layouts received incorrect scroll position calculations.

Files Changed

• Fix file: src/Controls/src/Core/Handlers/Items2/ItemsViewHandler2.iOS.cs (+2, -1)
  • Line ~149: Replace hardcoded UICollectionViewScrollDirection.Vertical with Controller.GetScrollDirection()
• Test file: src/Controls/tests/TestCases.HostApp/Issues/Issue33852.cs (+85, new)
  • Uses CollectionView2 with horizontal layout, button to ScrollTo item 15, label showing scroll state
• Test file: src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue33852.cs (+24, new)
  • UI test ProgrammaticScrollToWorksWithHorizontalLayout - taps ScrollToButton, verifies IndexLabel text

PR Discussion Summary

• No reviewer disagreements or inline review comments
• CI pipeline (maui-pr-uitests) was triggered by team member sheiksyedm
• Author validated fix on Android, Windows, iOS, Mac

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #33853	Replace hardcoded UICollectionViewScrollDirection.Vertical with Controller.GetScrollDirection() in ScrollToRequested	⏳ PENDING (Gate)	ItemsViewHandler2.iOS.cs (+2/-1)	Original PR - matches CV1 fix pattern

---

🚦 Gate — Test Verification

---

📝 Review Session — Fixed the collection view scroll to issue · 345ea8d

---

Result: ✅ PASSED
Platform: ios
Mode: Full Verification

• Tests FAIL without fix ✅
• Tests PASS with fix ✅

Test Filter: Issue33852
Fix File Validated: src/Controls/src/Core/Handlers/Items2/ItemsViewHandler2.iOS.cs

---

🔧 Fix — Analysis & Comparison

---

📝 Review Session — Fixed the collection view scroll to issue · 345ea8d

---

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
1	try-fix (claude-sonnet-4.5)	Query ItemsLayout.Orientation from VirtualView cast to StructuredItemsView, convert to UICollectionViewScrollDirection	✅ PASS	1 file (+12/-1)	More verbose, extra cast + null check
2	try-fix (claude-opus-4.6)	Read UICollectionViewCompositionalLayout.Configuration.ScrollDirection directly from native layout	✅ PASS	1 file (+5/-1)	Clean, direct, but tied to CompositionalLayout type
3	try-fix (gpt-5.2)	Infer direction heuristically from ContentSize vs Bounds dimensions	✅ PASS	1 file (+20/-1)	Fragile: depends on content being realized; could fail on empty/first-render
4	try-fix (gpt-5.2-codex)	Compute target offset directly from item frame using SetContentOffset, bypassing ScrollToItem entirely	✅ PASS	1 file (+42/-3)	Much more complex, 45 lines; changes scrolling mechanism fundamentally
5	try-fix (gemini)	Use Controller.GetScrollDirection() - same as PR's fix	✅ PASS	1 file (+1/-1)	Identical to PR fix
6	try-fix (claude-sonnet-4.5 R2)	Check both UICollectionViewFlowLayout.ScrollDirection and UICollectionViewCompositionalLayout.Configuration.ScrollDirection	✅ PASS	1 file (+11/-1)	More complex version of Attempt 2
7	try-fix (gpt-5.2 R2)	ScrollRectToVisible with complex viewport-rect calculation using AdjustedContentInset	✅ PASS	1 file (+80/-2)	Very complex, 80+ lines; changes scrolling mechanism entirely
8	try-fix (gemini R2)	ScrollRectToVisible with simple GetLayoutAttributesForItem.Frame	✅ PASS	1 file (+6/-2)	Simple but ignores ScrollToPosition alignment (Start/Center/End)
PR	PR #33853	Replace hardcoded UICollectionViewScrollDirection.Vertical with Controller.GetScrollDirection()	✅ PASS (Gate)	1 file (+2/-1)	Original PR - cleanest, uses existing infrastructure

Exhausted: Yes (rate limit hit after attempt 9; 8 of 8 attempts passed; all key approaches covered)
Selected Fix: PR's fix — Controller.GetScrollDirection() is the simplest, most direct, and reuses existing infrastructure that already correctly tracks the scroll direction. Only 2 lines changed.

Cross-Pollination Summary

Model	Round 2	Round 3
claude-sonnet-4.5	NEW IDEA (FlowLayout check - ran as #6)	NEW IDEA (caching - not run, rate limited)
claude-opus-4.6	NO NEW IDEAS	—
gpt-5.2	NEW IDEA (ScrollRectToVisible - ran as #7)	NEW IDEA (force layout - not run, rate limited)
gpt-5.2-codex	NO NEW IDEAS	—
gemini-3-pro-preview	NEW IDEA (ScrollRectToVisible - ran as #8)	NO NEW IDEAS

---

📋 Report — Final Recommendation

---

📝 Review Session — Fixed the collection view scroll to issue · 345ea8d

---

✅ Final Recommendation: APPROVE

Summary

PR #33853 fixes a one-line bug in the CV2 (CollectionView2) iOS/MacCatalyst handler where ScrollToRequested hardcoded UICollectionViewScrollDirection.Vertical, causing ScrollTo to silently do nothing for horizontal layouts. The fix replaces the hardcoded value with Controller.GetScrollDirection(), matching how CV1 already handled this.

---

Root Cause

In ItemsViewHandler2.iOS.cs, ScrollToRequested always passed UICollectionViewScrollDirection.Vertical to ScrollToPositionExtensions.ToCollectionViewScrollPosition(). For a horizontal layout, this mapped ScrollToPosition.Start to UICollectionViewScrollPosition.Top instead of UICollectionViewScrollPosition.Left, causing ScrollToItem to silently no-op (cannot scroll vertically when the view is horizontal).

---

Fix Quality

The fix is correct, minimal, and well-aligned with existing patterns.

• Only 2 lines changed in source (1 line added for scrollDirection, 1 line updated)
• Controller.GetScrollDirection() is already used elsewhere in the same method for content size checks (lines ~197-206)
• ItemsViewController2.GetScrollDirection() returns a cached ScrollDirection property updated during layout configuration
• Identical pattern to CV1 at src/Controls/src/Core/Handlers/Items/ItemsViewHandler.iOS.cs:111 which uses _layout.ScrollDirection
• 8 independent try-fix attempts confirmed this is the cleanest approach

---

PR Title & Description Review

Title: [iOS/MacCatalyst] Fix CollectionView ScrollTo for horizontal layouts

• ✅ Platform prefix correct
• ✅ Describes the fix clearly
• Minor note: could say "CV2" to distinguish from CV1, but current title is clear enough

Description: Good structure with NOTE block, root cause, and fix description. Accurate.

---

Code Review Findings

🟡 Minor Issues (non-blocking)

1. Missing newline at end of file (both test files)

• src/Controls/tests/TestCases.HostApp/Issues/Issue33852.cs (line 85)
• src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue33852.cs (line 24)
• Both end with } with no trailing newline. Standard convention is to add one.

2. Unnecessary string interpolation

• src/Controls/tests/TestCases.HostApp/Issues/Issue33852.cs line ~72:

  _indexLabel.Text = $"The CollectionView is scrolled";  // $ is unnecessary, no interpolation

  Should be: _indexLabel.Text = "The CollectionView is scrolled";

3. Extra whitespace in StackLayout

• src/Controls/tests/TestCases.HostApp/Issues/Issue33852.cs line ~63:

  Children =
  {
      _indexLabel,
       scrollToButton,  // extra leading space
      _collectionView

✅ Looks Good

• Fix file change is clean, minimal, and correct
• GetScrollDirection() is correctly placed before ToCollectionViewScrollPosition - no timing issues since layout direction is set during SetLayout
• Test uses CollectionView2 (not CollectionView) - correctly targets the CV2 handler
• [Category(UITestCategories.CollectionView)] appropriate category
• Test correctly verifies functional behavior (label update via Scrolled event) rather than screenshots
• PlatformAffected.iOS | PlatformAffected.macOS correctly set in [Issue] attribute

---

Fix Exploration Summary

8 alternative approaches were tested (all passed), confirming the bug is well-understood and the fix space is simple:

Approach	Complexity	Verdict
PR: Controller.GetScrollDirection()	Minimal	✅ Best - 2 lines, reuses existing infrastructure
Query VirtualView.ItemsLayout.Orientation	Medium	✅ Works but bypasses controller
Read CompositionalLayout.Configuration.ScrollDirection	Medium	✅ Works, tied to native type
ContentSize vs Bounds heuristic	High	⚠️ Fragile on empty/pre-render state
Direct SetContentOffset from frame	Very high	✅ Works but 45 lines, fundamental change
ScrollRectToVisible simple	Low	⚠️ Ignores Start/Center/End alignment
ScrollRectToVisible complex	Very high	✅ Works but 80+ lines
FlowLayout + CompositionalLayout check	Medium	✅ Works but overly defensive

Selected Fix: PR's fix is the clear winner - minimal change, consistent with CV1, uses existing infrastructure.

---

📋 Expand PR Finalization Review

---

Title: ✅ Good

Current: [iOS/MacCatalyst] Fix CollectionView ScrollTo for horizontal layouts

Description: ✅ Good

Description needs updates. See details below.

✨ Suggested PR Description

[!NOTE]
Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Issue Details

CollectionView's programmatic ScrollTo does not work when using a horizontal ItemsLayout on iOS/MacCatalyst. After calling ScrollTo(index, position: ScrollToPosition.Start, animate: true), the scroll position remains unchanged.

Root Cause

In the CV2 iOS handler (ItemsViewHandler2.iOS.cs), the scroll direction was hardcoded to UICollectionViewScrollDirection.Vertical when calculating the UICollectionViewScrollPosition. This caused incorrect scroll position values to be computed for horizontal layouts.

Description of Change

In ScrollToRequested, replaced the hardcoded UICollectionViewScrollDirection.Vertical with a call to Controller.GetScrollDirection(), which dynamically retrieves the actual scroll direction from the controller. This matches the approach already used in the CV1 handler (ItemsViewHandler.iOS.cs).

Changed file: src/Controls/src/Core/Handlers/Items2/ItemsViewHandler2.iOS.cs

Fix reference (CV1 pattern followed):

maui/src/Controls/src/Core/Handlers/Items/ItemsViewHandler.iOS.cs

Line 110 in 52f9fc2

Controller.CollectionView.ScrollToItem(indexPath,

Platforms

Platform	Status	Notes
iOS	✅ Fixed	Bug was here — horizontal scroll now works
Mac (MacCatalyst)	✅ Fixed	Bug was here — horizontal scroll now works
Android	✅ No regression	Unaffected (uses different handler)
Windows	✅ No regression	Unaffected (uses different handler)

Issues Fixed

Fixes #33852

Code Review: ✅ Passed

Code Review: PR #33853

Code Review Findings

---

✅ Fix in ItemsViewHandler2.iOS.cs — Correct

Change:

// Before
var position = Items.ScrollToPositionExtensions.ToCollectionViewScrollPosition(
    args.ScrollToPosition, UICollectionViewScrollDirection.Vertical);

// After
var scrollDirection = Controller.GetScrollDirection();
var position = Items.ScrollToPositionExtensions.ToCollectionViewScrollPosition(
    args.ScrollToPosition, scrollDirection);

This is a minimal, correct fix. Controller.GetScrollDirection() returns ScrollDirection from ItemsViewController2, which reads from the layout. The same pattern (Controller.GetScrollDirection()) is already used in the same file at line 197 for EnsureContentSizeForScrollDirection, so this is consistent with existing code.

The CV1 handler (ItemsViewHandler.iOS.cs) uses _layout.ScrollDirection directly, which achieves the same result — reading the actual layout direction rather than assuming vertical.

---

🟡 Potential Test Flakiness — TestCases.Shared.Tests/Tests/Issues/Issue33852.cs

Issue: After tapping the ScrollTo button, the test immediately reads the label text with FindElement — no waiting for the label to update.

App.WaitForElement("ScrollToButton");
App.Tap("ScrollToButton");
var firstIndexText = App.FindElement("IndexLabel").GetText();  // ⚠️ No wait
Assert.That(firstIndexText, Is.EqualTo("The CollectionView is scrolled"));

ScrollTo is called with animate: true, making it asynchronous. The Scrolled event that updates the label fires as the collection view scrolls — but there's a race between the animation starting and the test reading the label. On a slow device or under load, the label may still show "ItemIndex: 0" (initial value from _indexLabel = new Label { Text = "ItemIndex: 0" }) when the assertion runs.

Recommendation: Wait for the expected label value before asserting:

App.WaitForElement("ScrollToButton");
App.Tap("ScrollToButton");
App.WaitForElement("IndexLabel");
// Optionally: wait for text to change, or use WaitFor with expected value
var firstIndexText = App.FindElement("IndexLabel").GetText();
Assert.That(firstIndexText, Is.EqualTo("The CollectionView is scrolled"));

A more robust fix would use a polling approach or animate: false for deterministic testing, since the goal is to verify the scroll happened, not that it animated smoothly.

---

🟡 Whitespace Inconsistency — TestCases.HostApp/Issues/Issue33852.cs

File: src/Controls/tests/TestCases.HostApp/Issues/Issue33852.cs, line 63

Children =
{
    _indexLabel,
     scrollToButton,   // ⚠️ extra leading space
    _collectionView
}

There is an extra space before scrollToButton that doesn't match the indentation of the surrounding items. Minor cosmetic issue.

---

🟡 Missing Trailing Newline — Both New Test Files

Both new test files (Issue33852.cs in HostApp and in Shared.Tests) are missing a trailing newline at end of file. The git diff shows \ No newline at end of file for both. Minor but worth fixing for consistency.

---

✅ Test Structure — Good

• [Issue] attribute present with correct tracker, number, description, and PlatformAffected.iOS | PlatformAffected.macOS
• AutomationId values set on all interactive elements (ScrollToButton, IndexLabel, TestCollectionView)
• Uses CollectionView2 (which maps to CV2 handler via CollectionViewHostBuilderExtentions.cs)
• Test inherits from _IssuesUITest
• [Category(UITestCategories.CollectionView)] applied
• Test method name ProgrammaticScrollToWorksWithHorizontalLayout is descriptive

---

Summary

Severity	Finding
✅	Core fix is correct and consistent with CV1 and existing CV2 code patterns
🟡	UI test may be flaky due to no wait after animated ScrollTo
🟡	Extra whitespace on line 63 of HostApp test
🟡	Missing trailing newline in both new test files

---