Interaction

Every step decides what the user can touch while it is showing.

{ id: "post", target: "post-ride", interaction: "advance-on-press" }

Mode	The target	The rest of the screen	Advances when
`block` (default)	not pressable	not pressable	the user presses Next
`passthrough`	fully interactive	not pressable	the user presses Next
`advance-on-press`	press is caught by the tour	not pressable	the user presses the highlighted area

block

The safe default. A full-screen shield absorbs everything, including presses inside the hole, so the highlight is purely visual and nobody can wander off mid-tour.

Use it for anything explanatory.

passthrough

The shield is removed and the real element works normally. The tour does not advance by itself, so pair it with a step the user can leave through Next, or with a gate that resolves once they have done the thing.

tsOpen in Claude

Open in ChatGPT

{
  id: "try-filter",
  target: "filter",
  title: "Try a filter",
  interaction: "passthrough",
  gate: ({ context }) => context.hasFiltered,
  gateTimeoutMs: 30000,
  onGateTimeout: "skip",
}

Note what that costs you: the user's real press runs your real handler. If that handler navigates or mutates data, it happens mid-tour.

advance-on-press

The rest of the screen stays blocked, and a catcher sits over the hole. Pressing it advances the tour. The underlying element is not pressed.

That last part is deliberate and it is the same on both platforms. Letting the real press through would mean a tour step could fire a navigation or a mutation as a side effect, and it cannot be made to behave identically on React Native, where the library cannot attach a listener to your element. One behaviour everywhere beats a slightly richer one on web only.

On web the catcher is a real <button> with an accessible name, so a keyboard or screen-reader user can advance the same way.

The rule that matters

Never ask a user to press something that produces no visible change.

This is the reason action-driven tour steps get abandoned, and it is not a limitation of any mechanism. An early version of the tour this library grew out of said "Tap Find Pool" while Find Pool was already the selected segment. Pressing it did nothing visible, so the user could not tell whether the tour was broken or waiting on them. The step was correct, the copy was correct, and the experience was still bad.

Before you write an advance-on-press step, check that pressing it changes something the user can see. Advancing the tour itself counts, as long as the card visibly moves on.

Choosing

Reach for block unless you have a reason not to. Use advance-on-press when the gesture is the lesson, like "swipe here" or "tap the plus button". Use passthrough when the user genuinely needs to operate the app, and accept that their real handler runs.