skip to content

In SwiftUI, a photo card's tap handler either swallows taps on a heart icon inside it or never fires; how do gesture, highPriorityGesture and simultaneousGesture decide which runs?

level: seniorimportance: must knowfreq 58%

answer

  1. parent versus child precedence
  2. lower, higher or same priority
  3. GestureMask and its four options
  4. isEnabled maps to a mask

basics

~20 s

gesture(:) gives the card's gesture lower precedence than gestures its subviews define, so the heart wins; highPriorityGesture(:) makes the card win, so the heart never fires; simultaneousGesture(_:) runs both. A GestureMask or isEnabled narrows which gestures stay active.

solid answer

~40 s

The modifier that attaches the parent's gesture decides. `gesture(_:)` attaches it with **lower** precedence than gestures defined by the view, so a tap on the heart runs only the heart's handler, while a tap on the caption reaches the card. `highPriorityGesture(_:)` attaches it with **higher** precedence: every tap, the heart's included, runs only the card's handler. `simultaneousGesture(_:)` processes it alongside the existing gestures, so a heart tap runs both. Each takes `including: GestureMask` (`.all` by default, `.gesture`, `.subviews`, `.none`) to switch off the new gesture or the subviews' gestures, and `gesture(_:isEnabled:)` is defined as `including: isEnabled ? .all : .subviews`. That is how a zoomable photo inside a gallery enables its pan only when zoomed in.

code

swift · 19 lines
swift
import SwiftUI

struct GalleryCard: View {
    @State private var log: [String] = []

    var body: some View {
        VStack(spacing: 12) {
            Image(systemName: "heart.fill")
                .onTapGesture { log.append("heart") }   // the child's own gesture
            Text("Sunset over the bay")
        }
        .padding()
        // .gesture(...)             heart tap: "heart" only; caption tap: "card"
        // .highPriorityGesture(...) any tap: "card" only; the heart never fires
        .simultaneousGesture(        // heart tap: "heart" and "card"
            TapGesture().onEnded { log.append("card") }
        )
    }
}

go deeper

for a junior

Recall that gesture, highPriorityGesture and simultaneousGesture attach a gesture with lower, higher or equal precedence to the view's existing gestures.

for a middle

Predict the outcome for a parent and a child tap under each modifier, and explain the four GestureMask options and the isEnabled shorthand.

for a senior

Diagnose real conflicts in order: hit area, every gesture on the path, the attaching modifier; prefer disabling a gesture by state over raising its priority.

for a principal

Set conventions for shared containers such as galleries and cards, so features do not add high-priority gestures that silently break child controls.

## Three ways to attach a gesture to a parent A conflict between a parent's gesture and a child's is decided by **how the parent's gesture is attached**, not by the gesture itself. SwiftUI has three view modifiers for this, and Apple documents each with the same example: a `VStack` holding a heart `Image` with its own `onTapGesture`, plus a plain rectangle, with a tap gesture attached to the stack. | Modifier on the parent | Precedence | Tap on the heart | Tap on the plain area | |---|---|---|---| | `gesture(_:including:)` | lower than gestures the view defines | heart only | parent | | `highPriorityGesture(_:including:)` | higher than gestures the view defines | parent only | parent | | `simultaneousGesture(_:including:)` | same, processed together | heart **and** parent | parent | Read the symptoms against this table. "The card's tap swallows the heart" means the card uses `highPriorityGesture`. "The card's tap never fires on the heart" is `gesture(_:)` doing what it is documented to do. If both should react, the card needs `simultaneousGesture`. ## GestureMask: narrowing what stays active Each of the three modifiers takes `including mask: GestureMask`, which defaults to `.all`. The mask controls how adding this gesture affects other gestures recognised by the view and its subviews: - **`.all`**: the added gesture and the subviews' gestures are both enabled (the default). - **`.gesture`**: only the added gesture is enabled; the subviews' gestures are switched off. - **`.subviews`**: the subviews' gestures stay enabled; the added gesture is switched off. - **`.none`**: the added gesture and the subviews' gestures are both switched off. A selection mode is a typical use of `.gesture`: while the user is picking cards, `highPriorityGesture(select, including: .gesture)` lets the card's selection tap run and switches off the gestures inside it, so a heart cannot toggle mid-selection. Outside that mode, the same card attaches nothing, or attaches with `.subviews` so its own gesture is off and the children behave normally. The `isEnabled:` overloads are thin wrappers over this. The iOS 27.0 SDK spells out the body of `gesture(_:isEnabled:)` as `self.gesture(gesture, including: isEnabled ? .all : .subviews)`, and the high-priority and simultaneous variants follow the same pattern. Because those bodies are compiled into your app, they also build for an iOS 17 deployment target. iOS 18 adds overloads that also take a `name:` string. ## Diagnosing a conflict When a gesture misbehaves in a real screen, work through it in order: 1. **Check the hit area.** If the gesture never fires on empty space, the problem is hit testing; `contentShape` fixes it, and no priority change will. 2. **List every gesture on the path.** Include convenience modifiers such as `onTapGesture` on children and gestures that container views add for themselves. 3. **Read the attaching modifier.** `gesture`, `highPriorityGesture` or `simultaneousGesture` on the parent predicts the outcome from the table above. 4. **Switch, do not stack.** Replace the attaching modifier, or disable one side with a mask or `isEnabled`, rather than adding more gestures to force a winner. 5. **Test on a device with real fingers.** Controls such as `Button` handle their own touches, and a parent's high-priority tap can take taps from them too; confirm the interaction rather than assume it. ## Inside a horizontally scrolling gallery A zoomable photo page sits inside a gallery that the user swipes through. A `DragGesture` on the page that pans the photo competes with the container's own swiping. The common answer is not a priority modifier but **disabling the pan when it is not needed**: `gesture(pan, isEnabled: scale > 1)`. At 1x the pan is switched off and horizontal drags belong to the gallery; once the user has zoomed in, the pan takes over. How scroll views themselves recognise and page is covered in the lesson on lazy stacks and paging. ## Mistakes that come up in review - **Reaching for `highPriorityGesture` to fix a tap that never fires.** If the cause is hit testing, the higher priority also starts stealing taps from every child. - **Assuming the innermost gesture always wins.** That is true only while the parent uses `gesture(_:)`. - **Disabling with `.none` when only the parent's gesture should go.** `.none` also switches off the children's gestures; `.subviews` keeps them. - **Confusing these modifiers with `simultaneously(with:)` and `exclusively(before:)`.** Those combine two gestures into one value on the same view; they do not set priority between a parent and its children.

  • What does gesture(_:including: .subviews) do, and when would you write it?
    It attaches the gesture switched off while leaving the subviews' gestures enabled. It is exactly what `gesture(_:isEnabled: false)` compiles to, so you write it when a gesture should exist only in some states, such as a pan that applies only while a photo is zoomed in.
  • When is simultaneousGesture the right fix rather than highPriorityGesture?
    When both handlers should run: a card that records every tap for analytics while its heart keeps toggling. `highPriorityGesture` is for when the parent must override its children, for example while a selection mode treats any tap on the card as a selection and child taps must not fire.
  • How do you keep a heart tap from also triggering the card, while taps elsewhere still reach the card?
    Attach the card's gesture with plain `gesture(_:)`. Its gesture has lower precedence than gestures the card's subviews define, so a tap on the heart runs only the heart's handler and a tap anywhere else on the card reaches the card's gesture.

  • The innermost view's gesture always wins, whatever modifier the parent uses
  • highPriorityGesture is the fix whenever a tap does not fire
  • simultaneousGesture runs the parent's handler only when the child's handler fails
  • GestureMask.none disables only the gesture being added
  • exclusively(before:) sets priority between a parent's gesture and a child's