a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
desertthunder.dev
hypermedia
frontend
signals
1---
2version: 1.0
3updated: 2025-10-18
4---
5
6# Event Handling
7
8VoltX provides declarative event handling through `data-volt-on-*` attributes with automatic access to special scoped references.
9
10## Event Binding Syntax
11
12Event handlers are attached using the `data-volt-on-{eventName}` attribute
13
14The attribute value can be:
15
16- A function reference from the scope: `handleClick`
17- An inline expression: `count.set(count.get() + 1)`
18- A method call: `myObject.method()`
19
20## Scoped References
21
22Event handlers have access to two special scoped references that are automatically injected:
23
24### `$el` - The Target Element
25
26The `$el` reference provides access to the DOM element that the event handler is bound to.
27
28**Type:** [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element)
29
30### `$event` - The Event Object
31
32The `$event` reference provides access to the native browser event object.
33
34**Type:** [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) (or specific event type like `MouseEvent`, `KeyboardEvent`, etc.)
35
36## Event Types
37
38VoltX.js aims to support all standard DOM events through `data-volt-on-*`:
39
40**Mouse Events:**
41
42- `click`, `dblclick`
43- `mousedown`, `mouseup`
44- `mouseover`, `mouseout`, `mouseenter`, `mouseleave`
45- `mousemove`
46
47**Keyboard Events:**
48
49- `keydown`, `keyup`, `keypress`
50
51**Form Events:**
52
53- `submit`, `reset`
54- `input`, `change`
55- `focus`, `blur`
56
57**Touch Events:**
58
59- `touchstart`, `touchend`, `touchmove`, `touchcancel`
60
61**Other Events:**
62
63- `scroll`, `resize`
64- `load`, `error`
65- Any custom events
66
67## Implementation Details
68
69When an event handler is bound, VoltX.js:
70
711. Creates a new scope that extends the component scope
722. Injects `$el` (the bound element) and `$event` (the event object) into this scope
733. Evaluates the expression in this enhanced scope
744. If the expression returns a function, calls it with the event
75
76The event listener is automatically cleaned up when the element is unmounted.