Maui Gestures

.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.

AllowDrop defaults to false

Drop targets silently ignore drops if you forget this property.

Using TapGestureRecognizer for hover effects

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

---

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.

---

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: davidortinau
• Source: davidortinau/maui-skills
• License: MIT

Install and usage instructions live in the source repository linked above.