Published on

The Geometric Premise of Hit Testing: Why a SwiftUI Container Needs contentShape to Be Fully Tappable

Authors
  • avatar
    Name
    Jack Qin
    Twitter

We hold an assumption about "tappable area" so plain we never think it through: a view's tappable area is as big as the view. In most UI frameworks this assumption holds, so we attach onTap to a row's container and take it for granted that the whole row is tappable. SwiftUI has a different, more low-level geometric premise here: by default its hit testing covers only the pixels occupied by visible leaf subviews, not the entire frame the container declares. The gaps inside the container that "look like part of it" (Spacer, the spacing between leading and trailing) are, as far as hit testing is concerned, dead zones.

This post isn't about how to write one particular settings row; it's about dissecting this geometric premise: why "visible area" and "hittable area" are two separate concepts in SwiftUI, why contentShape is the bridge connecting them, and why that bridge must be placed before the gesture. Understand this and you're facing not just one settings-row bug, but a whole class of "declared frame ≠ actual hit area" interaction traps.

The symptom: only the right half responds

In the settings menu, users complained "it takes forever to open." It's not actually slow — tapping the left half does nothing, only tapping the right side (the arrow area) opens it. Users tap repeatedly, most taps miss, and the subjective experience becomes "the screen takes forever to respond." These rows are rendered via the @expo/ui/swift-ui SwiftUI bridge (the branch where isLiquidGlassAvailable() is true).

A standard settings row: a label on the left, an accessory (arrow) on the right, a large gap in between. onTapGesture is attached to the container, but there's no content shape:

const modifiers = []
if (onPress) {
  modifiers.push(onTapGesture(onPress)) // only leaf subviews are hit-tested
}

;<LabeledContent label={<Label title="Flow Meter" systemImage="gauge" />} modifiers={modifiers}>
  <SUIImage systemName="chevron.right" />
</LabeledContent>
// Tapping the left / middle of the row does nothing.

The mechanism: visible area ≠ hittable area

Attaching onTapGesture(...) to a SwiftUI container view (LabeledContent, HStack, VStack, a row with Spacer) does not make the whole row tappable. The reason is SwiftUI hit testing's default geometry: it only hit-tests visible leaf subviews (Text / Label / Image), and the container itself — along with the gaps stretched open inside it by Spacer — has no hittable geometry.

This splits "visible" and "hittable" into two things. Visually, the row is a continuous block from left to right; in hit testing, it's two islands — "the few characters of the leading label + the trailing arrow" — with the whole gap in between as a dead zone. A tap registers only if it lands exactly on some visible subview, and the only visible subview always on the right in a settings row is that arrow — which precisely explains "only the right half responds."

A container in SwiftUI is by default "present in the layout sense, transparent in the hit sense." It defines how subviews arrange but doesn't claim its own frame should receive taps. To make it claim that, you have to explicitly give it a hit shape.

The fix: declare the whole frame as the hit area with contentShape

contentShape(shapes.rectangle()) explicitly defines the hittable area as the view's entire frame, including spacers and gaps — it rewrites "hittable area" from "follows the visible subviews by default" to "equals the shape I declare."

import { contentShape, onTapGesture, shapes } from '@expo/ui/swift-ui/modifiers'

// Order matters: contentShape first, then gesture.
modifiers.push(contentShape(shapes.rectangle()), onTapGesture(onPress))

This is exactly what @expo/ui's own contentShape doc comment emphasizes:

"This modifier is essential for making entire view areas (including Spacer or empty space) interactive. Without it, only visible elements like Text or Image respond to tap gestures."

The complete correct shape:

const modifiers = []
if (onPress) {
  modifiers.push(
    contentShape(shapes.rectangle()), // the whole frame becomes hittable
    onTapGesture(onPress)
  )
}

;<LabeledContent label={<Label title="Flow Meter" systemImage="gauge" />} modifiers={modifiers}>
  <SUIImage systemName="chevron.right" />
</LabeledContent>
// The whole row is tappable.

Why the order can't be reversed: a modifier is a directed pipeline

contentShape must come before onTapGesture — this isn't a style convention but a direct consequence of SwiftUI's modifier evaluation direction. SwiftUI applies modifiers outside-in: the one written earlier expands the view first, and the one written later works on the already-expanded basis. For the gesture to take effect correctly, it must "see" an already-expanded content shape — so the shape-expanding contentShape must come first.

Put contentShape after onTapGesture, and at the moment the gesture takes effect it still sees the default leaf-only hit geometry — equivalent to not adding the contentShape at all. This is a classic "declaration order is semantics" API — both modifiers present, both spelled correctly, and it silently fails merely because the order is reversed.

Outcomes by tier:

  • Good: a LabeledContent settings row with [contentShape(shapes.rectangle()), onTapGesture(onPress)]. The whole row is tappable, consistent with the visual affordance (whole-row highlight / arrow).
  • Base: a leaf Text/Image with onTapGesture and no content shape — fine, because a leaf has no empty interior, its frame already equals the content. In other words, this geometric premise only bites when the frame is larger than the visible content.
  • Bad: a container with onTapGesture but no contentShape — the gaps are dead zones.
  • Bad: contentShape placed after onTapGesture — order reversed, equivalent to not adding it.

Verification: the unit test is mute here

This branch (isLiquidGlassAvailable() is true) renders the SwiftUI bridge, which Vitest can't render — and the RN fallback path (Pressable) doesn't have this bug, so the green unit tests prove nothing. You must verify on a real device / "Designed for iPad on Mac," and specifically tap the leading edge and middle of each tappable row, not just the trailing accessory — because the trailing area happens to land on the only visible leaf, tapping it always succeeds and completely masks the dead-zone problem. If a row is "intermittently responsive," first suspect a missing contentShape before hypothesizing performance / navigation issues.

The available modifiers are under @expo/ui/build/swift-ui/modifiers/: contentShape, shapes (rectangle/roundedRectangle/capsule/…), onTapGesture, disabled are all exposed.

The transferable layer

Set aside SwiftUI and @expo/ui's specific APIs, and there are two transferable lessons.

"Visible area" and "hittable/interactive area" are two independent geometries — don't assume they coincide. SwiftUI's container hit trap is just one example — CSS pointer-events, a transparent element blocking clicks on the layer below, whether padding counts as click area, an SVG fill: none path not receiving events — they're all the same class of problem: the boundary you see and the boundary the event system recognizes are two different geometries. When designing a tappable composite control, first ask: how much of this area is gap that's "visible but not tappable"? Have I explicitly declared the whole block hittable?

When an API's semantics depend on declaration order, an order error is a silent failure. contentShape having to come before onTapGesture is essentially the same as many "pipeline" APIs (middleware order, CSS cascade, shader pass order) — the elements are all there, and getting the order wrong makes it silently not work. When you meet this kind of API, remember the compiler and unit tests usually can't catch order errors; the only guard is understanding its evaluation direction.

Discuss on Twitter • View on GitHub