lily/event
Event handlers attach browser events to DOM elements using CSS selectors.
Each handler produces a message that gets sent to the
Store.
Handlers target elements using standard CSS selector strings and use
event delegation for dynamic elements (e.g., on_click with data-msg
attributes). They’re set up once and persist until page unload
import lily/event
pub fn main() {
store.new(Model(count: 0), with: update)
|> component.mount("#app", to_html: element.to_string, view: app)
|> event.on_click(selector: "#increment", handler: fn() { Increment })
|> event.on_click(selector: "#decrement", handler: fn() { Decrement })
|> event.on_input(selector: "#name", decoder: decode_name_input)
|> client.start
}
fn decode_name_input(event: Dynamic) -> Result(Message, Nil) {
use target <- result.try(dynamic.field("target", dynamic.dynamic)(event))
use value <- result.try(dynamic.field("value", dynamic.string)(target))
Ok(SetName(value))
}
All event handlers are JavaScript-only (@target(javascript)).
Values
pub fn on_blur(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires when an element loses focus.
pub fn on_change(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(String) -> message,
) -> client.Runtime(model, message)Fires when an input value changes (after focus is lost). For real-time
updates, use on_input instead.
pub fn on_click(
runtime: client.Runtime(model, message),
selector selector: String,
decoder decoder: fn(String) -> Result(message, Nil),
) -> client.Runtime(model, message)Fires on click events using event delegation with data-msg attributes.
The decoder receives the data-msg attribute value and should return the
corresponding message. Elements must have a data-msg attribute to trigger
this handler.
pub fn on_context_menu(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires when the context menu is opened (usually right-click). Provides mouse coordinates (x, y) relative to the viewport.
pub fn on_copy(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires when text is copied to the clipboard.
pub fn on_cut(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires when text is cut to the clipboard.
pub fn on_double_click(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires on double-click events.
pub fn on_drag(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires repeatedly while an element is being dragged. Provides current mouse coordinates (x, y). Note: This fires many times during a drag operation, consider throttling if performing expensive operations.
pub fn on_drag_end(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires once when a drag operation ends (mouse released).
pub fn on_drag_over(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires repeatedly when a dragged element is over a valid drop target.
Provides mouse coordinates (x, y). Note: You may need to call
event.preventDefault() in the browser to enable dropping.
pub fn on_drag_start(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires once when a drag operation starts. Provides initial mouse coordinates (x, y).
pub fn on_drop(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires when a dragged element is dropped on a valid drop target. Provides drop coordinates (x, y).
pub fn on_focus(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires when an element receives focus.
pub fn on_input(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(String) -> message,
) -> client.Runtime(model, message)Fires immediately when an input value changes. For delayed updates (after
blur), use on_change instead.
pub fn on_key_down(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(String) -> message,
) -> client.Runtime(model, message)Fires when a key is pressed down. Receives the key name (e.g., “Enter”, “ArrowUp”, “a”).
pub fn on_key_up(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(String) -> message,
) -> client.Runtime(model, message)Fires when a key is released. Receives the key name (e.g., “Enter”, “ArrowUp”, “a”).
pub fn on_mouse_down(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires when a mouse button is pressed down. Provides mouse coordinates (x, y) relative to the viewport.
pub fn on_mouse_enter(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires when the mouse enters an element’s boundary. Does not bubble.
pub fn on_mouse_leave(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires when the mouse leaves an element’s boundary. Does not bubble.
pub fn on_mouse_move(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires repeatedly while the mouse moves over an element. Provides current mouse coordinates (x, y). Note: This can fire very frequently, consider throttling for expensive operations.
pub fn on_mouse_up(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires when a mouse button is released. Provides mouse coordinates (x, y) relative to the viewport.
pub fn on_paste(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires when text is pasted from the clipboard.
pub fn on_pointer_down(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires when a pointer (mouse, pen, touch) is pressed down. Provides pointer coordinates (x, y). Pointer events unify mouse, touch, and pen input.
pub fn on_pointer_move(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires repeatedly while a pointer moves over an element. Provides current pointer coordinates (x, y). Pointer events unify mouse, touch, and pen input.
pub fn on_pointer_up(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires when a pointer (mouse, pen, touch) is released. Provides pointer coordinates (x, y). Pointer events unify mouse, touch, and pen input.
pub fn on_resize(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires when an element is resized. Typically used on window with selector
“window”.
pub fn on_scroll(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires when an element’s scroll position changes.
pub fn on_submit(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires when a form is submitted. Prevents the browser’s default form submission behavior automatically.
pub fn on_touch_end(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn() -> message,
) -> client.Runtime(model, message)Fires when all touches are removed from the screen.
pub fn on_touch_move(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires repeatedly while a touch point moves across the screen. Provides touch coordinates (x, y). Note: This can fire very frequently.
pub fn on_touch_start(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Int, Int) -> message,
) -> client.Runtime(model, message)Fires when a touch point is placed on the screen. Provides initial touch coordinates (x, y).
pub fn on_wheel(
runtime: client.Runtime(model, message),
selector selector: String,
handler handler: fn(Float, Float) -> message,
) -> client.Runtime(model, message)Fires when the mouse wheel is scrolled. Provides scroll deltas (delta_x, delta_y) indicating scroll direction and amount.