Skip to content

AThevon/genjutsu / skills/_jutsu/swiftui-motion

swiftui-motion

Verified

SwiftUI animation foundations - withAnimation, transitions, the zoom navigation transition, matchedGeometryEffect, PhaseAnimator, KeyframeAnimator, springs, gestures.

FileKindSize
SKILL.mdskill md19.2 KB
references/gestures-swiftui.mdmarkdown10.6 KB
references/phase-keyframe-deep.mdmarkdown9.2 KB
references/springs-cheatsheet.mdmarkdown5.2 KB

references/gestures-swiftui.md

View on GitHub
# SwiftUI Gestures deep-dive

Gesture composition, conflict resolution, velocity, and the patterns that ship on every modern iOS app.
SwiftUI gestures are declarative; conflicts are resolved by composition, not by `.cancel()` calls.

---

## Gesture types reference

### TapGesture

```swift
.gesture(
    TapGesture(count: 2).onEnded { print("double tap") }
)
// Single tap is the default (count: 1)
```

Discrete (fires once on completion). `count:` recognizes N taps within the system double-tap interval.

### LongPressGesture

```swift
.gesture(
    LongPressGesture(minimumDuration: 0.5)
        .onChanged { _ in /* press detected, not yet "long" */ }
        .onEnded { _ in /* threshold crossed */ }
)
```

`minimumDuration` is the threshold; `maximumDistance` (default 10pt) is how far the finger can drift before the gesture cancels.

### DragGesture

```swift
.gesture(
    DragGesture(minimumDistance: 0, coordinateSpace: .global)
        .onChanged { value in offset = value.translation }
        .onEnded { value in
            withAnimation(.spring(.smooth)) { offset = .zero }
        }
)
```

`minimumDistance: 0` recognizes immediately on touch-down (use for drag-without-tap-fallback). `minimumDistance: 10` (default) means the user has to actually drag - taps still pass through to children. Pick deliberately:

| `minimumDistance` | Behavior |
|---|---|
| `0` | Recognizes on touch-down. Steals taps from children. Use for drag handles. |
| `10` (default) | Distinguishes drag from tap. Use for swipe-to-dismiss patterns. |
| `> 30` | Only "intentional" drags. Use for gesture overlays that must coexist with scrolling content. |

`coordinateSpace:` is the space `location` and `translation` are read in: `.local` (default), `.global`, or `.named(_:)`, a space an ancestor declares with `.coordinateSpace(.named("board"))`. The parameter is `some CoordinateSpaceProtocol` since iOS 17; the same three spellings compile against the older `CoordinateSpace` enum, but below iOS 17 the ancestor declares the space with `.coordinateSpace(name: "board")`.

**Read in `.global`, or in a named ancestor that does not move, whenever the gesture sits inside the `.offset` or `.scaleEffect` that its translation drives** (why: see "A drag that moves its own view" in the module). A header that drags its whole sheet is the usual case. `.local` only holds when the gesture is attached outside the modifier that moves the view (`.offset(...)` first, `.gesture(...)` after) and nothing above it moves; `.global` is right in both orders, which is why the example uses it. Named spaces are also what cross-view drags read in.

### MagnifyGesture (iOS 17+, replaces MagnificationGesture)

```swift
@State private var scale: CGFloat = 1
@State private var lastScale: CGFloat = 1

Image("photo")
    .scaleEffect(scale)
    .gesture(
        MagnifyGesture()
            .onChanged { value in scale = lastScale * value.magnification }
            .onEnded { _ in lastScale = scale }
    )
```

`value.magnification` is the cumulative pinch ratio since gesture start. Multiply by the previous `lastScale` to compose successive pinches. `MagnificationGesture` and `RotationGesture` are deprecated as of iOS / iPadOS / macOS / visionOS 27.2 (renamed to `MagnifyGesture` and `RotateGesture`), so new code should not use them.

### RotateGesture (iOS 17+, replaces RotationGesture)

```swift
@State private var rotation: Angle = .zero
@State private var lastRotation: Angle = .zero

Image("photo")
    .rotationEffect(rotation)
    .gesture(
        RotateGesture()
            .onChanged { value in rotation = lastRotation + value.rotation }
            .onEnded { _ in lastRotation = rotation }
    )
```

Rare on phones (one-handed), more common on iPad and visionOS. Combine with `MagnifyGesture` via `.simultaneously(with:)` for a photo-editor-style canvas.

### SpatialTapGesture (iOS 16+, macOS 13+, watchOS 9+)

```swift
.gesture(
    SpatialTapGesture()
        .onEnded { value in
            print("tapped at \(value.location)")
        }
)
```

Same as `TapGesture` but reports the local location. Useful for ripple effects, zoom-to-point on photo viewers, drawing apps.

---

## Composition operators

### `.simultaneously(with:)` - parallel recognition

```swift
let drag = DragGesture(coordinateSpace: .global).onChanged { offset = $0.translation }
let magnify = MagnifyGesture().onChanged { scale = $0.magnification }

.gesture(drag.simultaneously(with: magnify))
```

Both gestures recognize together. Use for canvas / photo viewers that need pan + zoom at the same time.

### `.sequenced(before:)` - one must complete first

```swift
let press = LongPressGesture(minimumDuration: 0.3)
let drag = DragGesture()

.gesture(
    press.sequenced(before: drag)
        .onChanged { value in
            switch value {
            case .first: break  // long-press in progress
            case .second(_, let dragValue):
                if let d = dragValue { offset = d.translation }
            }
        }
)
```

Classic "press-and-hold-then-drag" pattern (iOS reorder, drag-to-pin on Maps). The drag won't recognize until the long-press completes.

### `.exclusively(before:)` - one OR the other

```swift
let tap = TapGesture()
let longPress = LongPressGesture()

.gesture(tap.exclusively(before: longPress))
```

If both could recognize, the first one wins. Rare in practice - usually you want simultaneous or sequenced.

---

## Conflict resolution patterns

### Vertical scroll vs horizontal swipe

```swift
DragGesture(minimumDistance: 10)
    .onChanged { value in
        // Claim the gesture only if the drag is dominantly horizontal
        let horizontal = abs(value.translation.width)
        let vertical = abs(value.translation.height)
        guard horizontal > vertical * 1.5 else { return }
        offset = value.translation.width
    }
```

By the time `onChanged` first fires, the user has moved 10pt+. Compare horizontal vs vertical magnitude before claiming - otherwise you fight the parent `ScrollView`.

### Tap vs drag

```swift
// Drag with minimumDistance: 0 swallows taps - children never receive them.
DragGesture(minimumDistance: 0)

// Use minimumDistance: 5+ to let taps pass through.
DragGesture(minimumDistance: 5)
```

Default is 10. Lower it only if you need touch-down feedback (e.g., "press anywhere to dismiss" style overlays).

### Native nav back-swipe vs custom horizontal pan (iOS)

The system back-gesture lives on the leading edge (left in LTR). Custom horizontal pans there will fight it. Detect and skip:

```swift
DragGesture(minimumDistance: 10)
    .onChanged { value in
        // Ignore drags that started near the leading edge - leave them to the system
        guard value.startLocation.x > 30 else { return }
        offset = value.translation.width
    }
```

Same logic for the trailing edge if you support right-handed swipe-back, or for the bottom edge (home indicator).

---

## GestureMask + simultaneousGesture

`.simultaneousGesture(_:including:)` adds a gesture without claiming the input - both your gesture and the existing one recognize:

```swift
.simultaneousGesture(
    LongPressGesture().onEnded { _ in showContextMenu() },
    including: .gesture
)
```

`GestureMask` controls which gestures are eligible to fire on this view:

| Mask | Recognizes |
|---|---|
| `.gesture` | Only the gesture you just attached |
| `.subviews` | Only gestures attached to descendant views |
| `.all` | Both (default) |
| `.none` | Disable all gestures on this subtree |

Use `.subviews` when you want a parent overlay to coexist with child taps; use `.gesture` to suppress children entirely.

---

## Velocity / momentum

`DragGesture.Value` exposes prediction APIs that account for the user's flick velocity:

| Property | Meaning |
|---|---|
| `translation` | Current cumulative translation since gesture start |
| `predictedEndTranslation` | Where translation would land if released now (includes momentum) |
| `predictedEndLocation` | Same in absolute coordinates |
| `velocity` (iOS 17+) | `CGSize` of points per second on x/y |

Fling pattern using prediction:

```swift
DragGesture()
    .onEnded { value in
        let predictedX = value.predictedEndTranslation.width
        let dismissThreshold: CGFloat = 100
        if predictedX > dismissThreshold {
            withAnimation(.spring(.smooth)) { offset.width = 1000 }
            // trigger dismiss
        } else {
            withAnimation(.interactiveSpring()) { offset = .zero }
        }
    }
```

Direct velocity (iOS 17+):

```swift
.onEnded { value in
    let vx = value.velocity.width  // pt/s
    if abs(vx) > 800 { /* fast flick */ }
}
```

---

## Common patterns

### Swipe-to-dismiss (modal sheet)

```swift
@State private var dragOffset: CGFloat = 0

VStack { /* sheet content */ }
    .offset(y: dragOffset)
    .gesture(
        DragGesture(minimumDistance: 10, coordinateSpace: .global)
            .onChanged { value in
                dragOffset = max(0, value.translation.height)  // only downward
            }
            .onEnded { value in
                let predicted = value.predictedEndTranslation.height
                if predicted > 150 {
                    withAnimation(.spring(.smooth)) { dragOffset = 800 }
                    onDismiss()
                } else {
                    withAnimation(.spring(.snappy)) { dragOffset = 0 }
                }
            }
    )
```

### Pull-to-refresh

```swift
List { /* rows */ }
    .refreshable {
        await viewModel.reload()
    }
```

iOS 15+. Built-in, accessible, respects scroll-views. Don't reinvent with `DragGesture`.

### Pinch-to-zoom an image

```swift
@State private var scale: CGFloat = 1
@State private var lastScale: CGFloat = 1

Image("photo")
    .scaleEffect(scale)
    .gesture(
        MagnifyGesture()
            .onChanged { value in
                scale = max(1, min(4, lastScale * value.magnification))
            }
            .onEnded { _ in lastScale = scale }
    )
```

Always clamp scale to a reasonable range (typically 1...4 for photos, 0.5...10 for maps).

### Double-tap-to-zoom

```swift
.gesture(
    TapGesture(count: 2).onEnded {
        withAnimation(.spring(.smooth)) {
            scale = scale > 1 ? 1 : 2
            lastScale = scale
        }
    }
)
```

Use alongside `MagnifyGesture` via `.simultaneously(with:)` so users can both pinch and double-tap.

---

## Sources

- [Apple Composing SwiftUI gestures](https://developer.apple.com/documentation/swiftui/composing-swiftui-gestures)
- [Apple Gesture protocol](https://developer.apple.com/documentation/swiftui/gesture)
- [Apple DragGesture.Value](https://developer.apple.com/documentation/swiftui/draggesture/value)
- [WWDC23 Beyond scroll views](https://developer.apple.com/videos/play/wwdc2023/10159/)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall