lustre/event

advanced

pub fn advanced(
  name: String,
  handler: decode.Decoder(@internal Handler(msg)),
) -> @internal Attribute(msg)

Listens for the given event and then runs the given decoder on the event object. This decoder is capable of conditionally stopping propagation or preventing the default behaviour of the event by returning a Handler record with the appropriate flags set. This makes it possible to write event handlers for more-advanced scenarios such as handling specific key presses.

Note: it is not possible to conditionally stop propagation or prevent the default behaviour of an event when using server components. Your event handler runs on the server, far away from the browser!

Note: if you are developing a server component, it is important to also use server_component.include to state which properties of the event you need to be sent to the server.

debounce

</>

pub fn debounce(
  event: @internal Attribute(msg),
  delay: Int,
) -> @internal Attribute(msg)

Use Lustre’s built-in event debouncing to wait a delay after a burst of events before dispatching the most recent one. You can visualise debounced events like so:

 original : --a-b-cd--e----------f--------
debounced : ---------------e----------f---

This is particularly useful for server components where many events in quick succession can introduce problems because of network latency.

Note: debounced events inherently introduce latency. Try to consider typical interaction patterns and experiment with different delays to balance responsiveness and update frequency.

emit

</>

pub fn emit(event: String, data: json.Json) -> effect.Effect(msg)

Dispatches a custom message from a Lustre component. This lets components communicate with their parents the same way native DOM elements do.

Any JSON-serialisable payload can be attached as additional data for any event listeners to decode. This data will be on the event’s detail property.

handler

</>

pub fn handler(
  dispatch message: msg,
  prevent_default prevent_default: Bool,
  stop_propagation stop_propagation: Bool,
) -> @internal Handler(msg)

Construct a Handler that can be used with advanced to conditionally stop propagation or prevent the default behaviour of an event.

on

</>

pub fn on(
  name: String,
  handler: decode.Decoder(msg),
) -> @internal Attribute(msg)

Listens for the given event and then runs the given decoder on the event object. If the decoder succeeds, the decoded event is dispatched to your application’s update function. If it fails, the event is silently ignored.

The event name is typically an all-lowercase string such as “click” or “mousemove”. If you’re listening for non-standard events (like those emitted by a custom element) their event names might be slightly different.

Note: if you are developing a server component, it is important to also use server_component.include to state which properties of the event you need to be sent to the server.

on_blur

</>

pub fn on_blur(msg: msg) -> @internal Attribute(msg)

on_change

</>

pub fn on_change(
  msg: fn(String) -> msg,
) -> @internal Attribute(msg)

Listens for change events on elements such as <input>, <textarea> and <select>. This handler automatically decodes the string value of the input and passes it to the given message function. This is commonly used to implement controlled inputs.

on_check

</>

pub fn on_check(msg: fn(Bool) -> msg) -> @internal Attribute(msg)

Listens for change events on <input type="checkbox"> elements. This handler automatically decodes the boolean value of the checkbox and passes it to the given message function. This is commonly used to implement controlled inputs.

on_click

</>

pub fn on_click(msg: msg) -> @internal Attribute(msg)

on_focus

</>

pub fn on_focus(msg: msg) -> @internal Attribute(msg)

on_input

</>

pub fn on_input(
  msg: fn(String) -> msg,
) -> @internal Attribute(msg)

Listens for input events on elements such as <input>, <textarea> and <select>. This handler automatically decodes the string value of the input and passes it to the given message function. This is commonly used to implement controlled inputs.

on_keydown

</>

pub fn on_keydown(
  msg: fn(String) -> msg,
) -> @internal Attribute(msg)

Listens for key down events on an element, and dispatches a message with the current key being pressed.

on_keypress

</>

pub fn on_keypress(
  msg: fn(String) -> msg,
) -> @internal Attribute(msg)

Listens for key presses on an element, and dispatches a message with the current key being pressed.

on_keyup

</>

pub fn on_keyup(
  msg: fn(String) -> msg,
) -> @internal Attribute(msg)

Listens for key up events on an element, and dispatches a message with the current key being released.

on_mouse_down

</>

pub fn on_mouse_down(msg: msg) -> @internal Attribute(msg)

on_mouse_enter

</>

pub fn on_mouse_enter(msg: msg) -> @internal Attribute(msg)

on_mouse_leave

</>

pub fn on_mouse_leave(msg: msg) -> @internal Attribute(msg)

on_mouse_out

</>

pub fn on_mouse_out(msg: msg) -> @internal Attribute(msg)

on_mouse_over

</>

pub fn on_mouse_over(msg: msg) -> @internal Attribute(msg)

on_mouse_up

</>

pub fn on_mouse_up(msg: msg) -> @internal Attribute(msg)

on_submit

</>

pub fn on_submit(
  msg: fn(List(#(String, String))) -> msg,
) -> @internal Attribute(msg)

Listens for submit events on a <form> element and receives a list of name/value pairs for each field in the form. Files are not included in this list: if you need them, you can write your own handler for the "submit" event and decode the non-standard detail.formData property manually.

This handler is best paired with the formal package which lets you process form submissions in a type-safe way.

This will automatically call prevent_default to stop the browser’s native form submission. In a Lustre app you’ll want to handle that yourself as an Effect.

prevent_default

</>

pub fn prevent_default(
  event: @internal Attribute(msg),
) -> @internal Attribute(msg)

Indicate that the event should have its default behaviour cancelled. This is equivalent to calling event.preventDefault() in JavaScript.

Note: this will override the conditional behaviour of an event handler created with advanced.

stop_propagation

</>

pub fn stop_propagation(
  event: @internal Attribute(msg),
) -> @internal Attribute(msg)

Indicate that the event should not propagate to parent elements. This is equivalent to calling event.stopPropagation() in JavaScript.