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>

Safe Areas

For .NET 10+ safe-area work, use SafeAreaEdges on the root container instead of hard-coded iOS-only padding:

Value	Effect
SafeAreaEdges.Container	Insets only the device bezel/notch boundary
SafeAreaEdges.SoftInput	Also avoids the on-screen keyboard
SafeAreaEdges.All	All edges including status bar and navigation areas

<!-- XAML: apply on the outermost layout that should respect device edges -->
<Grid SafeAreaEdges="Container">
    ...
</Grid>

// C# Markup
new Grid { SafeAreaEdges = SafeAreaEdges.Container }

Keep safe-area behavior declarative. Test with notches, rounded corners, desktop title bars, and soft keyboard scenarios when the page uses edge-to-edge layout. If the MAUI version is unknown, use maui-current-apis before changing APIs.

Gestures

• Use TapGestureRecognizer for click/tap. Do not use removed or obsolete click gesture APIs.
• Use PointerGestureRecognizer for hover/desktop pointer affordances.
• Use PanGestureRecognizer, SwipeGestureRecognizer, and PinchGestureRecognizer only where the gesture maps to an obvious UI action.
• Do not attach competing gestures to deeply nested controls without testing hit-testing and scrolling interactions.
• Preserve accessibility alternatives: commands, buttons, menu items, keyboard accelerators, or semantic descriptions as appropriate.

Animations

• Prefer built-in async animation helpers such as FadeTo, ScaleTo, TranslateTo, and RotateTo for view animations.
• Await or coordinate animations so state changes do not race.
• Cancel or ignore stale animations when view models unload or commands rerun.
• Avoid animation-only feedback for important state; expose semantic state and visual states too.
• Keep list item animations modest; animating many recycled cells can hurt scrolling performance.

GraphicsView

Use GraphicsView for custom drawing, charts, signatures, or lightweight visualizations:

• Put drawing code in an IDrawable.
• Treat Draw(ICanvas canvas, RectF dirtyRect) as a hot path: avoid allocations, blocking I/O, async calls, and service lookups.
• Store state outside the drawable and call Invalidate() when state changes.
• Handle pointer/touch input at the view or page layer and translate it to drawing state.
• For important information in the drawing, provide accessible alternatives outside the canvas: wrap the GraphicsView alongside a Label or use SemanticProperties.Description on the view so screen readers announce it. AutomationId on the GraphicsView enables UI-test targeting.
• Use SemanticScreenReader.Announce for dynamic changes that must be audible.
• If drawing stutters or allocates heavily, consult maui-performance.

Validation Checklist

• CollectionView owns its scrolling and has empty/loading behavior where data can be absent.
• Safe-area code matches the detected MAUI version and target platforms.
• Gestures have accessible alternatives for critical actions.
• Animations cannot leave the UI in stale state after cancellation or navigation.
• GraphicsView drawing is allocation-conscious and exposes important content outside the canvas.