maui-controls-deep-dive

MAUI Controls Deep Dive

Use this skill when the user is already working with MAUI controls and needs details beyond basic layout guidance. Keep control choices aligned with current MAUI APIs.

Response Checklist

• For list scenarios, prefer CollectionView with EmptyView, RemainingItemsThreshold, and stable AutomationId hooks.
• For edge-to-edge scenarios, call out .NET 10 SafeAreaEdges values.
• For GraphicsView, keep IDrawable.Draw hot-path guidance and add semantic alternatives (SemanticProperties / accessible companion UI).

Workflow

1. Inspect the target framework and whether the UI is XAML, C# Markup, or another MAUI UI style.
2. Identify the control area: CollectionView, safe area, gestures, animations, or GraphicsView.
3. Apply the focused guidance below. Route broad accessibility audits to maui-accessibility; for GraphicsView-specific semantics, apply SemanticProperties and AutomationId directly (see GraphicsView section). Route performance profiling to maui-performance.
4. Validate the control on the intended device sizes and platforms.

CollectionView

Use CollectionView for repeated data and let it own scrolling:

• Do not wrap it in ScrollView.
• Use EmptyView, header/footer, and surrounding Grid rows for non-item UI.
• Use RemainingItemsThreshold / RemainingItemsThresholdReachedCommand for incremental loading.
• Use SelectionMode, SelectedItem, and SelectionChangedCommand instead of tap gestures on item roots when selection is the intent.
• Keep item templates lightweight. Avoid nested layouts and expensive converters in large lists.
• Prefer stable AutomationId values on the list and critical item controls.
• For .NET 10 iOS/Mac Catalyst behavior, check current handler guidance before opting into or reverting CollectionView handlers.

Example state shell:

<Grid RowDefinitions="Auto,*">
    <ActivityIndicator
        AutomationId="orders-loading"
        IsRunning="{Binding IsBusy}"
        IsVisible="{Binding IsBusy}" />

    <CollectionView
        Grid.Row="1"
        AutomationId="orders-list"
        ItemsSource="{Binding Orders}"
        RemainingItemsThreshold="5"
        RemainingItemsThresholdReachedCommand="{Binding LoadMoreCommand}">
        <CollectionView.EmptyView>
            <Label
                AutomationId="orders-empty"
                Text="No orders found." />
        </CollectionView.EmptyView>
    </CollectionView>
</Grid>