Gestures

The gesture vocabulary

Convenience modifiers cover the common cases:

Card()
    .onTapGesture { select() }
    .onTapGesture(count: 2) { zoom() }
    .onLongPressGesture { showContextActions() }

The full form attaches a gesture value — a recogniser you configure and compose:

Card()
    .gesture(
        DragGesture()
            .onChanged { value in offset = value.translation }
            .onEnded { value in finishDrag(velocity: value.velocity) }
    )

DragGesture's callbacks receive a value carrying translation (offset since start), location, startLocation, velocity, and predictedEndTranslation — where the drag would land if the finger's momentum continued. That last one is how card-dismissal UIs decide "flick away or snap back" from a short, fast swipe.

@State vs @GestureState

The dividing line: does the value outlive the finger?

struct DraggableCard: View {
    @GestureState private var dragOffset = CGSize.zero   // only while dragging
    @State private var position = CGSize.zero            // survives between drags

    var body: some View {
        Card()
            .offset(
                x: position.width + dragOffset.width,
                y: position.height + dragOffset.height
            )
            .gesture(
                DragGesture()
                    .updating($dragOffset) { value, state, _ in
                        state = value.translation        // write via the in-out param
                    }
                    .onEnded { value in
                        position.width += value.translation.width
                        position.height += value.translation.height
                    }
            )
            .animation(.spring, value: dragOffset)
    }
}

Read the division of labour:

• .updating($dragOffset) writes the live offset through an inout parameter while the finger moves. The moment the gesture ends or is cancelled, the framework resets dragOffset to .zero — you cannot forget to, because there is nothing to write.
• .onEnded commits the result into persistent state. It runs on a successful end only, which is exactly right for a commit.
• The spring bound to dragOffset animates the automatic snap-back for free.

This split — live value resets itself; committed value is explicit — is the pattern behind every polished drag interaction you have used: sheet pull-downs, photo pinch-zoom that springs back past the limit, swipe-to-reply in messaging apps.

Composing gestures

Real interfaces layer gestures, and SwiftUI makes the arbitration explicit:

// Both at once — pinch and rotate a photo simultaneously:
MagnifyGesture().simultaneously(with: RotateGesture())

// One then the other — long-press to lift, then drag:
LongPressGesture(minimumDuration: 0.3).sequenced(before: DragGesture())

// First to succeed wins:
TapGesture(count: 2).exclusively(before: TapGesture(count: 1))

sequenced(before:) is the one that unlocks a familiar interaction: the "hold to pick up, then move" of home-screen icon rearranging. The drag half never starts unless the long-press half completed — and until it does, the scroll view keeps its claim on vertical movement, which is why the pattern feels trustworthy inside scrolling content.

When a gesture competes with a system one (a drag inside a ScrollView), the system gesture wins by default — usually what you want. .highPriorityGesture(_:) reverses that; treat it as a last resort, because stealing touches from scrolling is how apps end up feeling broken.