SwiftUI Gestures

Comprehensive guide to SwiftUI gesture recognition with composition patterns, state management, and accessibility integration.

When to Use This Skill

• Implementing tap, drag, long press, magnification, or rotation gestures
• Composing multiple gestures (simultaneously, sequenced, exclusively)
• Managing gesture state with GestureState
• Creating custom gesture recognizers
• Debugging gesture conflicts or unresponsive gestures
• Making gestures accessible with VoiceOver
• Cross-platform gesture handling (iOS, macOS, axiom-visionOS)

Example Prompts

These are real questions developers ask that this skill is designed to answer:

1. "My drag gesture isn't working - the view doesn't move when I drag it. How do I debug this?"

→ The skill covers DragGesture state management patterns and shows how to properly update view offset with @GestureState

2. "I have both a tap gesture and a drag gesture on the same view. The tap works but the drag doesn't. How do I fix this?"

→ The skill demonstrates gesture composition with .simultaneously, .sequenced, and .exclusively to resolve gesture conflicts

3. "I want users to long press before they can drag an item. How do I chain gestures together?"

→ The skill shows the .sequenced pattern for combining LongPressGesture with DragGesture in the correct order

4. "My gesture state isn't resetting when the gesture ends. The view stays in the wrong position."

→ The skill covers @GestureState automatic reset behavior and the updating parameter for proper state management

5. "VoiceOver users can't access features that require gestures. How do I make gestures accessible?"

→ The skill demonstrates .accessibilityAction patterns and providing alternative interactions for VoiceOver users

---

Choosing the Right Gesture (Decision Tree)

What interaction do you need?

├─ Single tap/click?
│  └─ Use Button (preferred) or TapGesture
│
├─ Drag/pan movement?
│  └─ Use DragGesture
│
├─ Hold before action?
│  └─ Use LongPressGesture
│
├─ Pinch to zoom?
│  └─ Use MagnificationGesture
│
├─ Two-finger rotation?
│  └─ Use RotationGesture
│
├─ Multiple gestures together?
│  ├─ Both at same time? → .simultaneously
│  ├─ One after another? → .sequenced
│  └─ One OR the other? → .exclusively
│
└─ Complex custom behavior?
   └─ Create custom Gesture conforming to Gesture protocol

---

Pattern 1: Basic Gesture Recognition

TapGesture

❌ WRONG (Custom tap on non-semantic view)

Text("Submit")
  .onTapGesture {
    submitForm()
  }

Problems:

• Not announced as button to VoiceOver
• No visual press feedback
• Doesn't respect accessibility settings

✅ CORRECT (Use Button for tap actions)

Button("Submit") {
  submitForm()
}
.buttonStyle(.bordered)

When to use TapGesture: Only when you need tap data (location, count) or non-standard tap behavior:

Image("map")
  .onTapGesture(count: 2) { // Double-tap for details
    showDetails()
  }
  .onTapGesture { location in // Single tap to pin
    addPin(at: location)
  }

---

DragGesture

❌ WRONG (Direct state mutation in gesture)

@State private var offset = CGSize.zero

var body: some View {
  Circle()
    .offset(offset)
    .gesture(
      DragGesture()
        .onChanged { value in
          offset = value.translation // ❌ Updates every frame, causes jank
        }
    )
}

Problems:

• View updates on every drag event (60-120 times per second)
• No way to reset to original position
• Loses intermediate state if drag cancelled

✅ CORRECT (Use GestureState for temporary state)

@GestureState private var dragOffset = CGSize.zero
@State private var position = CGSize.zero

var body: some View {
  Circle()
    .offset(x: position.width + dragOffset.width,
            y: position.height + dragOffset.height)
    .gesture(
      DragGesture()
        .updating($dragOffset) { value, state, _ in
          state = value.translation // Temporary during drag
        }
        .onEnded { value in
          position.width += value.translation.width // Commit final
          position.height += value.translation.height
        }
    )
}

Why: GestureState automatically resets to initial value when gesture ends, preventing state corruption.

---

LongPressGesture

@GestureState private var isDetectingLongPress = false
@State private var completedLongPress = false

var body: some View {
  Text("Press and hold")
    .foregroundStyle(isDetectingLongPress ? .red : .blue)
    .gesture(
      LongPressGesture(minimumDuration: 1.0)
        .updating($isDetectingLongPress) { currentState, gestureState, _ in
          gestureState = currentState // Visual feedback during press
        }
        .onEnded { _ in
          completedLongPress = true // Action after hold
        }
    )
}

Key parameters:

• minimumDuration: How long to hold (default 0.5 seconds)
• maximumDistance: How far finger can move before cancelling (default 10 points)

---

MagnificationGesture

@GestureState private var magnificationAmount = 1.0
@State private var currentZoom = 1.0

var body: some View {
  Image("photo")
    .scaleEffect(currentZoom * magnificationAmount)
    .gesture(
      MagnificationGesture()
        .updating($magnificationAmount) { value, state, _ in
          state = value.magnification
        }
        .onEnded { value in
          currentZoom *= value.magnification
        }
    )
}

Platform notes:

• iOS: Pinch gesture with two fingers
• macOS: Trackpad pinch
• visionOS: Pinch gesture in 3D space

---

RotationGesture

@GestureState private var rotationAngle = Angle.zero
@State private var currentRotation = Angle.zero

var body: some View {
  Rectangle()
    .fill(.blue)
    .frame(width: 200, height: 200)
    .rotationEffect(currentRotation + rotationAngle)
    .gesture(
      RotationGesture()
        .updating($rotationAngle) { value, state, _ in
          state = value.rotation
        }
        .onEnded { value in
          currentRotation += value.rotation
        }
    )
}

---

Pattern 2: Gesture Composition

Simultaneous Gestures

Use when: Two gestures should work at the same time

@GestureState private var dragOffset = CGSize.zero
@GestureState private var m