diff --git a/docs/user-interface/controls/collectionview/index.md b/docs/user-interface/controls/collectionview/index.md index dc93704c1b..8f1e9f2b0a 100644 --- a/docs/user-interface/controls/collectionview/index.md +++ b/docs/user-interface/controls/collectionview/index.md @@ -1,7 +1,7 @@ --- title: "CollectionView" description: "The .NET MAUI CollectionView displays a scrollable list of selectable data items, using different layout specifications." -ms.date: 08/19/2025 +ms.date: 07/08/2026 --- # CollectionView @@ -36,6 +36,24 @@ builder.ConfigureMauiHandlers(handlers => ::: moniker-end +::: moniker range=">=net-maui-11.0" + +## Windows CollectionView handler in .NET 11 + +In .NET MAUI 11, Windows uses the `Microsoft.Maui.Controls.Handlers.Items2.CollectionViewHandler2` handler for by default. The handler is controlled by the `Microsoft.Maui.RuntimeFeature.IsWindowsCollectionView2HandlerEnabled` switch, which is on by default. The `UseWindowsCollectionView2Handler` MSBuild property maps to this switch. + +This WinUI `ItemsRepeater`-based handler improves virtualization and scrolling behavior, and aligns the Windows architecture with the optimized handlers on other platforms. Selection visuals are also different from the legacy Windows handler: selected items are highlighted with a border that wraps the item, and the multiple-selection UI differs from the previous `ListView`-based handler. + +If your app depends on legacy Windows behavior or custom handler assumptions, temporarily opt out while migrating by setting the `UseWindowsCollectionView2Handler` MSBuild property to `false` in your project file: + +```xml + + false + +``` + +::: moniker-end + ## CollectionView and ListView differences While the and APIs are similar, there are some notable differences: