/maui-gestures

name: maui-gestures
description: >
  Guidance for implementing tap, swipe, pan, pinch, drag-and-drop, and pointer
  gesture recognizers in .NET MAUI applications. Covers XAML and C# usage,
  combining gestures, and platform differences.
  USE FOR: "tap gesture", "swipe gesture", "pan gesture", "pinch gesture",
  "drag and drop", "pointer gesture", "gesture recognizer", "TapGestureRecognizer",
  "SwipeGestureRecognizer", "PanGestureRecognizer", "combine gestures".
  DO NOT USE FOR: animations triggered by gestures (use maui-animations),
  CollectionView swipe actions (use maui-collectionview), or custom drawing interaction (use maui-graphics-drawing).

.NET MAUI Gesture Recognizers

Deprecated API Warning

> ⚠️ In .NET 10, `ClickGestureRecognizer` is **deprecated**. Use > `TapGestureRecognizer` (touch/stylus) and `PointerGestureRecognizer` > (mouse hover/press) instead.

---

Common Mistakes

One `SwipeGestureRecognizer` per direction

A single recognizer handles only one direction. Adding multiple directions to one recognizer silently fails on most platforms.

<!-- ❌ Only fires for Left — Right is ignored -->
<SwipeGestureRecognizer Direction="Left,Right" Swiped="OnSwiped" />

<!-- ✅ Separate recognizer per direction -->
<SwipeGestureRecognizer Direction="Left" Swiped="OnSwiped" />
<SwipeGestureRecognizer Direction="Right" Swiped="OnSwiped" />

`AllowDrop` defaults to `false`

Drop targets silently ignore drops if you forget this property.

<!-- ❌ Drop never fires — AllowDrop defaults to false -->
<StackLayout>
  <StackLayout.GestureRecognizers>
    <DropGestureRecognizer Drop="OnDrop" />
  </StackLayout.GestureRecognizers>
</StackLayout>

<!-- ✅ Explicitly enable drops -->
<StackLayout>
  <StackLayout.GestureRecognizers>
    <DropGestureRecognizer AllowDrop="True" Drop="OnDrop" />
  </StackLayout.GestureRecognizers>
</StackLayout>

Using `TapGestureRecognizer` for hover effects

Tap recognizers don't track pointer movement. Use `PointerGestureRecognizer` for hover effects — it also enables the `PointerOver` visual state.

<!-- ❌ No hover tracking — user must tap to trigger -->
<Border>
  <Border.GestureRecognizers>
    <TapGestureRecognizer Command="{Binding HoverCommand}" />
  </Border.GestureRecognizers>
</Border>

<!-- ✅ Proper hover detection + visual state -->
<Border>
  <Border.GestureRecognizers>
    <PointerGestureRecognizer PointerEnteredCommand="{Binding HoverInCommand}"
                              PointerExitedCommand="{Binding HoverOutCommand}" />
  </Border.GestureRecognizers>
</Border>

---

Platform Differences That Bite

Pan delta coordinates differ by platform

| Platform | `TotalX` / `TotalY` relative to | |---|---| | iOS / Mac Catalyst | Start of gesture | | Android | **Previous event** (not start!) | | Windows | Start of gesture |

If sub-pixel accuracy matters, normalize Android deltas by accumulating them manually rather than using `TotalX`/`TotalY` directly.

Pointer hover is mouse/trackpad only

On touch devices, `PointerGestureRecognizer` events fire on press/release but **hover is not tracked** between touches. Don't rely on `PointerMoved` for touch-based UI.

Cross-app drag-and-drop

| Platform | Supported | |---|---| | iPadOS / Mac Catalyst | ✅ Yes | | Windows | ✅ Yes | | Android | ❌ No |

Secondary button (right-click)

| Platform | Behaviour | |---|---| | iOS / Mac Catalyst | `Buttons = ButtonsMask.Secondary` works | | Windows | `Buttons = ButtonsMask.Secondary` works | | Android | Falls back to long-press — no true right-click |

---

Gesture Combination Conflicts

Combining pan + swipe on the same view **conflicts on Android** — the swipe may consume the gesture before pan starts. Test on all platforms, or use only one at a time.

Combining tap + pan works well — tap fires on quick taps, pan fires on sustained drags.

---

MVVM Best Practice

Prefer **commands** over events for testable view models. Both work identically at runtime, but commands are easier to mock and test.

<!-- ✅ Bindable command — testable -->
<TapGestureRecognizer Command="{Binding TapCommand}" />

<!-- ⚠️ Event handler — requires code-behind, harder to unit-test -->
<TapGestureRecognizer Tapped="OnTapped" />

---

Quick Rules

1. One `SwipeGestureRecognizer` per direction 2. `PointerGestureRecognizer` for hover, not `TapGestureRecognizer` 3. `AllowDrop="True"` on drop targets — it defaults to `false` 4. Normalize pan deltas on Android (relative to previous event, not start) 5. Prefer commands over events for MVVM 6. Use `TapGestureRecognizer` instead of deprecated `ClickGestureRecognizer` (.NET 10) 7. Don't rely on `PointerMoved` for touch-based UI — hover doesn't track