RFC: Internal Event Propagation

[tzdesign]

What is it about?

stopPropagation should work in qwik as it does native in javascript

What's the motivation for this proposal?

Summary

Provide full, predictable control over DOM event propagation in Qwik so that event.stopPropagation() and event.stopImmediatePropagation() behave like native browser JavaScript across both user-defined and Qwik internal/system handlers (e.g. action submission, router SPA resets, form enhancement logic). Today, internal dispatch continues executing subsequent handlers even if a previous handler signaled propagation stop, leading to surprising side effects.

Motivation

Developers expect browser event semantics. In current Qwik versions:

• Custom on<Event>$ handlers can call event.stopPropagation() or event.preventDefault().
• Qwik augments certain elements (e.g. <form>) with internal system handlers (actions, SPA navigation, form serialization, optimistic UI, etc.).
• Qwik's internal composed handler arrays execute regardless of propagation stop requests in earlier handlers.

This causes:

• Inability to prevent internal action submission when business logic decides to abort.
• Harder composition with design-system components that rely on cancel / guard patterns.
• Divergence from platform mental model; debugging friction.
• Difficult to implement multi-step confirmation flows (e.g. destructive action "Are you sure?" dialogs common in mobile apps) because internal handlers (like action.submit) still fire even when a first-step handler attempts to gate or defer execution via stopPropagation().

Current form flow:

return jsx('form', {
  ...rest,
  action: action.actionPath,
  'preventdefault:submit': !reloadDocument,
  onSubmit$: [
    onSubmit$,              // developer-supplied
    !reloadDocument ? action.submit : undefined, // internal action
  ],
  method: 'post',
  'data-spa-reset': spaReset ? 'true' : undefined,
});

If onSubmit$ calls event.stopPropagation() (or even event.preventDefault()), action.submit still runs.

Goals

1. Respect stopPropagation() and stopImmediatePropagation() across any chained Qwik handler list.
2. Allow developers to cancel internal system logic (actions, SPA navigation) safely and declaratively, like they used to.

Current Behavior Details

Qwik normalizes multi-handlers (onClick$: [a, b, c]). Internally it iterates and invokes each registered QRL. The iteration does not check flags set by previous handlers (defaultPrevented, custom markers, etc.). System handlers are appended into these arrays or registered separately, bypassing native bubbling semantics because execution is flattened.

Proposed Solution / Feature

Proposed Design

Leverage the fact that Qwik already passes the native browser Event object through all handlers. Instead of creating a shadow/augmented event, simply observe native flags after each handler invocation.

Key idea: After each handler in a multi-handler list executes, check:

• event.cancelBubble (set by stopPropagation() and also by stopImmediatePropagation()). If true, stop invoking remaining handlers in the list for the current target.
• A lightweight internal flag ONLY if we need to distinguish stopImmediatePropagation() (optional). If differentiation isn't required, treating both the same is sufficient for the Qwik internal chaining use case.
• Optionally event.defaultPrevented for specific internal handlers (e.g. form auto-submit) that should respect a prevented default.

This keeps implementation minimal, avoids monkey-patching, and fully reuses native semantics already implemented and optimized by browsers.

Internal Implementation Sketch

1. Multi-handler executor pseudo code:

for (const handler of handlers) {
  await invoke(handler, ev);
  // Native event.stopPropagation() or stopImmediatePropagation() set cancelBubble
  if (ev.cancelBubble) break; // stop remaining handlers at this target
  // Optional: if we really need to distinguish stopImmediatePropagation we can lazy-patch only that method:
  // if ((ev as any)._qwikStopImmediate) break;
}

2. Internal/system handlers (actions, form enhancements) appear later in the handler list; if a user handler called stopPropagation(), they are skipped.
3. For handlers that should ALSO respect preventDefault(), wrap their execution:

if (!ev.defaultPrevented) {
  await actionSubmit(ev);
}

Rationale For Using cancelBubble

event.cancelBubble is a long-standing, standardized boolean alias internally flipped by both stopPropagation() and stopImmediatePropagation(). Reading it avoids patching and symbol bookkeeping. The inability to distinguish the two calls is acceptable because Qwik's current issue is continuation after ANY propagation stop request. If finer granularity is ever required, a minimal patch ONLY for stopImmediatePropagation can be added in strict mode.

Performance Considerations

• Single boolean read (ev.cancelBubble) after each handler (ultra-cheap, no augmentation cost).
• Optional extra boolean read for defaultPrevented when relevant.
• Zero monkey-patching in the common path; no additional allocations.
  Expected overhead: negligible compared to handler invocation itself.

Edge Cases

• Handlers that rely on internal action still firing despite stopPropagation: will need to remove now-unnecessary guards.
• Multiple identical QRLs: unchanged; each invocation can still stop subsequent ones.
• Nested portals / synthetic targets: Out of scope; native model still governs bubbling outside currentTarget.
• Async handlers: If a handler awaits, later handlers wait; stop requests after awaited continuation still honored because we check flags after each await returns.

Alternatives Considered

Shadow / augmented event with symbol flags – more code & minor overhead; no longer necessary.

Testing Strategy

• Unit: Multi-handler chain stops on stopPropagation & stopImmediatePropagation.
• Unit: Internal action handler not invoked after stopPropagation.
• Unit: defaultPrevented alone does NOT halt unless explicitly coded.
• Integration: Form submission aborted; network call not made.

Documentation Updates

Add section "Event Propagation Control" to Qwik docs:

• Explain legacy behavior.
• Explain internal handlers and how they react on cancelBubble

Open Questions

• Should preventDefault() ALSO skip internal submissions by default? (Likely yes for forms.)

Drawbacks

• Potential subtle breaks where apps unknowingly relied on legacy continuation.
• Slight runtime overhead.

Conclusion

Aligning Qwik's internal event handling with the native DOM propagation contract reduces surprise, improves composability, and simplifies app logic.

Links / References

No response

[shairez]

@tzdesign thanks! this sounds like a bug in the original implementation no?
if so, maybe it's worth opening a bug with a repro on the Qwik repo instead

[tzdesign]

I talked to @wmertens.
I looked at the implementation back then, and it shouldn't be hard to implement. Whether we do it in V2 or handle it as a bug doesn't matter.

We would like to do confirmation in a form, that's all.