{}} />` — will trigger a TypeScript error.
This occurs because these native events are not part of Solid's custom event type definitions.
-To solve this, `CustomEvents` and `CustomCaptureEvents` interfaces can be extended to include events from the `HTMLElementEventMap`:
+To solve this, the `CustomEvents` interface can be extended to include events from the `HTMLElementEventMap`:
To include all native events:
@@ -700,7 +715,6 @@ To include all native events:
declare module "solid-js" {
namespace JSX {
interface CustomEvents extends HTMLElementEventMap {}
- interface CustomCaptureEvents extends HTMLElementEventMap {}
}
}
```
diff --git a/src/routes/reference/jsx-attributes/data.json b/src/routes/reference/jsx-attributes/data.json
index ed7c4e98f..d1f72a49e 100644
--- a/src/routes/reference/jsx-attributes/data.json
+++ b/src/routes/reference/jsx-attributes/data.json
@@ -6,7 +6,7 @@
"bool.mdx",
"innerhtml-or-textcontent.mdx",
"on_.mdx",
- "on-and-oncapture.mdx",
+ "on.mdx",
"once.mdx",
"prop.mdx",
"ref.mdx",
diff --git a/src/routes/reference/jsx-attributes/on-and-oncapture.mdx b/src/routes/reference/jsx-attributes/on-and-oncapture.mdx
deleted file mode 100644
index a7d90dbf7..000000000
--- a/src/routes/reference/jsx-attributes/on-and-oncapture.mdx
+++ /dev/null
@@ -1,14 +0,0 @@
----
-title: on:* and oncapture:*
-order: 4
----
-
-For events with capital letters, or if you need to attach event handlers directly to a DOM element instead of optimized delegating via the document, use `on:*` in place of `on*`.
-
-```tsx
-
console.log("Welcome!")} />
-```
-
-This directly attaches an event handler (via [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)) to the `div`.
-
-Another special attribute is `oncapture:*`, which attaches the event handler with the option [`capture: true`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#capture), meaning that the event will get captured on the way down the DOM tree, instead of waiting for it to bubble up from its descendants. This results in calling this event handler before descendant handlers (in particular, before those descendants could potentially cancel bubbling via [`stopPropagation`](https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation)), and enables the handler to stop the event from descending via `stopPropagation`.
diff --git a/src/routes/reference/jsx-attributes/on.mdx b/src/routes/reference/jsx-attributes/on.mdx
new file mode 100644
index 000000000..d611ad486
--- /dev/null
+++ b/src/routes/reference/jsx-attributes/on.mdx
@@ -0,0 +1,35 @@
+---
+title: on:*
+order: 4
+---
+
+For events with capital letters, listener options, or if you need to attach event handlers directly to a DOM element instead of optimized delegating via the document, use `on:*` in place of `on*`.
+
+```tsx
+
console.log("Welcome!")} />
+```
+
+This directly attaches an event handler (via [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)) to the `div`.
+
+
New in v1.9.0
+
+An aditional special syntax that allows full control of [`capture`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#capture), [`passive`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#passive), [`once`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#once) and [`signal`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#signal) is an intersection or combination of `EventListenerObject` & `AddEventListenerOptions`, as follows:
+
+```tsx
+const handler = {
+ handleEvent(e) {
+ console.log(e)
+ },
+ once:true,
+ passive:false,
+ capture:true
+}
+
+
+
+// or inline
+
+
console.log("Weeeee!")}} />
+```
+
+This new syntax replaces the now deprecated `oncapture:` and it's future proof for any posible new event listener options.
diff --git a/src/routes/reference/jsx-attributes/on_.mdx b/src/routes/reference/jsx-attributes/on_.mdx
index af0a73d7c..c274af477 100644
--- a/src/routes/reference/jsx-attributes/on_.mdx
+++ b/src/routes/reference/jsx-attributes/on_.mdx
@@ -11,7 +11,7 @@ Event handlers in Solid typically take the form of `onclick` or `onClick` depend
Conceptually, this example attaches a `click` event listener (via [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)) to the `div`. However, Solid actually handles common UI events that bubble and are composed (such as `click`) at the document level, and then synthetically implements delegation (capturing and bubbling). This improves performance for these common events by reducing the number of event handlers.
-Note that `onClick` handles the event `click`; in general, event names get mapped to lower case. If you need to work with event names containing capital letters, see [`on:`](/reference/jsx-attributes/on-and-oncapture) which attaches event handlers directly (also avoiding fancy delegation via document).
+Note that `onClick` handles the event `click`; in general, event names get mapped to lower case. If you need to work with event names containing capital letters, or use listener options such once, passive, capture see [`on:`](/reference/jsx-attributes/on) which attaches event handlers directly (also avoiding fancy delegation via document).
Solid also supports passing a two-element array to the event handler to bind a value to the first argument of the event handler. This doesn't use `bind` or create an additional closure, so it is a highly optimized way of delegating events.
@@ -22,7 +22,7 @@ function handler(itemId, e) {
+;
```
Events are never rebound and the bindings are not reactive, as it is expensive to attach and detach listeners. Since event handlers are called like any other function each time an event fires, there is no need for reactivity; shortcut your handler if desired.