Add track Support to useOnWindow for Conditional Event Listeners

[jojojojojoj5564656465465]

What is it about?

This proposal suggests adding a track mechanism to useOnWindow in Qwik, similar to useTask$, to enable conditional event listeners based on reactive state changes.

What's the motivation for this proposal?

Unnecessary Event Listeners: Currently, useOnWindow always attaches event listeners, even when they are not needed (e.g., when a modal or dropdown is closed). This can lead to performance overhead and unnecessary event handling.
Manual Cleanup Complexity: Developers must manually manage event listener cleanup when using useTask$ with document.addEventListener, which is error-prone and less elegant than Qwik's built-in solutions.

Goals you are trying to achieve:

Conditional Event Listeners: Allow useOnWindow to dynamically add or remove event listeners based on reactive state (e.g., isOpen.value).
Simplified Code: Reduce boilerplate by eliminating the need for manual cleanup and useTask$ wrappers.
Consistency: Align useOnWindow with Qwik's reactive programming model, making it more intuitive for developers.

Any other context or information you want to share:

This feature would make useOnWindow more powerful and flexible, particularly for UI components like modals, dropdowns, and tooltips that need to respond to external clicks.
It would also improve performance by avoiding unnecessary event listeners.

Proposed Solution / Feature

Add a track option to useOnWindow to allow conditional event listener registration. The syntax could look like this:

useOnWindow(
  "mousedown",
  $((event) => {
    if (navBarRef.value && !navBarRef.value.contains(event.target as Node)) {
      isOpen.value = false;
    }
  }),
  { track: () => isOpen.value } // Only listen when `isOpen.value` is true
);

instead of

 useTask$(({ track, cleanup }) => {
    track(() => isOpen.value);
    if (!isOpen.value) return;

    const handleClickOutside = (event: MouseEvent) => {
      if (navBarRef.value && !navBarRef.value.contains(event.target as Node)) {
        isOpen.value &&= false;
      }
    };
   
    document.addEventListener("mousedown", handleClickOutside);
    cleanup(() =>
      document.removeEventListener("mousedown", handleClickOutside),
    );
  });

Links / References

No response

[wmertens]

It's a nice idea, but you can already do it like this:

import { component$, $, useSignal } from '@builder.io/qwik';

export default component$(() => {
  const toggle = useSignal(true)
  const xPos = useSignal(0)
  const yPos = useSignal(0)
  const posHandler = $((ev: MouseEvent) => {
    xPos.value = ev.clientX
    yPos.value = ev.clientY
  })

  // `window.onMouseMove$` is exactly the same as useOnWindow('mousemove', posHandler)
  return <div window:onMouseMove$={toggle.value && posHandler}>
    <button onClick$={() => toggle.value = !toggle.value}>{toggle.value?'Stop':'Start'} tracking</button>
    <div>x: {xPos.value} y: {yPos.value}</div>
  </div>;
});

Playground link

There is a bug though - if you start off with it disabled then it will not correctly add it back, I created QwikDev/qwik#8128.

---

That said, can we easily add this API? We need to move the condition to the attribute, so we need the function to be a QRL:

useOnWindow('mousemove', posHandler, $(() => toggle.value))

this would basically result in the attribute

<div window:onMouseMove$={$(() => toggle.value)().then(posHandler)} />

but in v1 we don't support promises on attributes.

we could also say that the enable flag has to be a Signal<bool>

useOnWindow('mousemove', posHandler, toggle)

that would be ok, we can easily get the equivalent of

<div window:onMouseMove$={toggle.value && posHandler} />

(at least in v2, not sure in v1)

---

So the question is, do we want to make this the API?

useOnXyz(type: string, handler: QRL<EventHandler>, enable?: Signal<bool>) => void

[jojojojojoj5564656465465]

Could you add track on useOnXyz()

[wmertens]

I proposed an API, I don't use track in there, what do you mean?