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.

<!-- ❌ 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

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

Secondary button (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

Gesture Recognizers API Reference

All gesture recognizers inherit from GestureRecognizer and are added via View.GestureRecognizers.

<Image>
  <Image.GestureRecognizers>
    <TapGestureRecognizer Tapped="OnTapped" />
  </Image.GestureRecognizers>
</Image>

var tap = new TapGestureRecognizer();
tap.Tapped += OnTapped;
image.GestureRecognizers.Add(tap);

---

Summary

---

TapGestureRecognizer

<Label Text="Tap me">
  <Label.GestureRecognizers>
    <TapGestureRecognizer NumberOfTapsRequired="2" Buttons="Primary"
                          Command="{Binding DoubleTapCommand}" />
  </Label.GestureRecognizers>
</Label>

var tap = new TapGestureRecognizer { NumberOfTapsRequired = 2, Buttons = ButtonsMask.Primary };
tap.Command = new Command(() => Debug.WriteLine("Double-tapped"));
label.GestureRecognizers.Add(tap);

---

SwipeGestureRecognizer

SwipedEventArgs: Direction, Parameter.

<BoxView Color="Teal">
  <BoxView.GestureRecognizers>
    <SwipeGestureRecognizer Direction="Left" Threshold="150" Swiped="OnSwiped" />
    <SwipeGestureRecognizer Direction="Right" Swiped="OnSwiped" />
  </BoxView.GestureRecognizers>
</BoxView>

var swipe = new SwipeGestureRecognizer { Direction = SwipeDirection.Left, Threshold = 150 };
swipe.Swiped += (s, e) => Debug.WriteLine($"Swiped {e.Direction}");
boxView.GestureRecognizers.Add(swipe);

---

PanGestureRecognizer

PanUpdatedEventArgs: StatusType (Started, Running, Completed), TotalX, TotalY, GestureId.

<Image Source="photo.png">
  <Image.GestureRecognizers>
    <PanGestureRecognizer PanUpdated="OnPanUpdated" />
  </Image.GestureRecognizers>
</Image>

var pan = new PanGestureRecognizer();
pan.PanUpdated += (s, e) => {
    if (e.StatusType == GestureStatus.Running)
    { image.TranslationX = e.TotalX; image.TranslationY = e.TotalY; }
};
image.GestureRecognizers.Add(pan);

---

PinchGestureRecognizer

PinchGestureUpdatedEventArgs: Scale, ScaleOrigin (Point), Status (Started, Running, Completed).

<Image Source="photo.png">
  <Image.GestureRecognizers>
    <PinchGestureRecognizer PinchUpdated="OnPinchUpdated" />
  </Image.GestureRecognizers>
</Image>

var pinch = new PinchGestureRecognizer();
pinch.PinchUpdated += (s, e) =>
{
    if (e.Status == GestureStatus.Running)
        image.Scale = Math.Clamp(image.Scale + (e.Scale - 1), 0.5, 3);
};
image.GestureRecognizers.Add(pinch);

---

DragGestureRecognizer

Label and Image auto-populate data packages. For custom data, set DragStartingEventArgs.Data.

<Label Text="Drag me" BackgroundColor="LightBlue">
  <Label.GestureRecognizers>
    <DragGestureRecognizer CanDrag="True" DragStarting="OnDragStarting" />
  </Label.GestureRecognizers>
</Label>

var drag = new DragGestureRecognizer { CanDrag = true };
drag.DragStarting += (s, e) =>
{
    e.Data.Text = viewModel.ItemId;
    e.Data.Properties["payload"] = viewModel.SelectedItem;
};
view.GestureRecognizers.Add(drag);

---

DropGestureRecognizer

<StackLayout BackgroundColor="LightGray">
  <StackLayout.GestureRecognizers>
    <DropGestureRecognizer AllowDrop="True" DragOver="OnDragOver" Drop="OnDrop" />
  </StackLayout.GestureRecognizers>
</StackLayout>

var drop = new DropGestureRecognizer { AllowDrop = true };
drop.Drop += async (s, e) => { var text = await e.Data.GetTextAsync(); };
target.GestureRecognizers.Add(drop);

PlatformArgs per platform:

---

PointerGestureRecognizer

PointerEventArgs.GetPosition(relativeTo) returns a Point?. Adding this recognizer enables the PointerOver VisualState.

<Border StrokeShape="RoundRectangle 8">
  <Border.GestureRecognizers>
    <PointerGestureRecognizer PointerEnteredCommand="{Binding HoverInCommand}"
                              PointerExitedCommand="{Binding HoverOutCommand}"
                              PointerMoved="OnPointerMoved" />
  </Border.GestureRecognizers>
  <VisualStateManager.VisualStateGroups>
    <VisualStateGroup Name="CommonStates">
      <VisualState Name="PointerOver">
        <VisualState.Setters>
          <Setter Property="BackgroundColor" Value="LightCyan" />
        </VisualState.Setters>
      </VisualState>
    </VisualStateGroup>
  </VisualStateManager.VisualStateGroups>
</Border>

var pointer = new PointerGestureRecognizer();
pointer.PointerMoved += (s, e) => Debug.WriteLine($"Pointer at {e.GetPosition(null)}");
border.GestureRecognizers.Add(pointer);

---

Combining Multiple Gestures

Add multiple recognizers to the same collection. The platform resolves conflicts.

<Image Source="card.png">
  <Image.GestureRecognizers>
    <TapGestureRecognizer Tapped="OnTapped" />
    <PanGestureRecognizer PanUpdated="OnPan" />
    <PinchGestureRecognizer PinchUpdated="OnPinch" />
    <PointerGestureRecognizer PointerEntered="OnHover" />
  </Image.GestureRecognizers>
</Image>