From 2a16b996e8e660428f5a4f737d2e98b1782ad2ee Mon Sep 17 00:00:00 2001 From: "Nicholas H.Tollervey" Date: Thu, 19 Feb 2026 11:51:14 +0000 Subject: [PATCH] Add call-out warning to describe handling events generated by dynamically created elements. --- docs/user-guide/events.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/user-guide/events.md b/docs/user-guide/events.md index 50a7e94..e11d2a7 100644 --- a/docs/user-guide/events.md +++ b/docs/user-guide/events.md @@ -34,6 +34,41 @@ The decorator attaches the function to all elements matching the selector. If multiple elements match, the function is called for each one when its event fires. +!!! warning + + The `@when` decorator only affects matching elements that exist + _when the decorator is first encountered_. If you dynamically add + matching elements _after_ `@when` is encountered, **they will not + be affected**. + + This reflects the browser-based capabilities that underpin + the `@when` decorator. Ultimately, + [JavaScript's `addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) + is called, and this also only affects elements that exist at the + time of the call. + + If you dynamically add new elements to the page, _you must also + indicate an event is to be handled for that new element_. For + instance, call `when` as a plain function, passing the new element + directly: + + ```python + from pyscript import web, when + + + def my_handler(event): + # Do stuff. + ... + + # Dynamimcally add a new element to the page. + el = web.button("Click me") + web.page.body.append(el) + + # Use when() as a plain function to attach the my_handler function + # to the new button's click event. + when("click", el)(my_handler) + ``` + ### Event types You can handle any browser event. Common ones include: