Skip to contents

Event & binding dispatch config

Source: R/wire.R
wire.Rd

Configure how an event handler or value binding is dispatched between the browser and the server. A single per-slot carrier, wire(), rides the slot it configures — an on* handler slot or a value/checked binding slot — so an event's timing, backpressure, and DOM-listener options live next to the handler/reactive they govern rather than in separate element-level lists.

Usage

wire_immediate()

wire_throttle(ms, leading = TRUE)

wire_debounce(ms)

wire_dom_opts(
  prevent_default = FALSE,
  stop_propagation = FALSE,
  capture = FALSE,
  passive = FALSE,
  filter = NULL
)

wire(subject = NULL, timing = NULL, coalesce = NULL, dom_opts = NULL)

Arguments

ms

Minimum interval (throttle) or quiet period (debounce) in milliseconds.

leading

If TRUE (default), fire immediately on the first event. If FALSE, wait for the timer before firing.

prevent_default

Call event.preventDefault() before dispatch.

stop_propagation

Call event.stopPropagation() before dispatch.

capture

Register the listener in the capture phase.

passive

Register the listener as passive.

filter

A JavaScript expression string, evaluated client-side with the event object bound to e; the event is dropped when it is falsy. NULL (the default) applies no filter.

subject

The handler or reactive the wire configures. The slot decides which: a bare callable means "bind" in value = / checked = and "handle" in an on* slot. NULL (the default) carries config only — used by widget wrappers that supply a default shape for the caller to override via merge().

timing

An irid_wire_timing shape (wire_immediate(), wire_throttle(), wire_debounce()), or NULL for the per-event default.

coalesce

Logical scalar, or NULL to derive from the timing mode.

dom_opts

A wire_dom_opts() record, or NULL.

Value

wire() returns an irid_wire; the timing constructors return an irid_wire_timing; wire_dom_opts() returns an irid_dom_opts.

Timing shapes

The timing constructors are pure shapes — they describe when an event fires and carry no other config:

  • wire_immediate(): Fires on every event with no rate limiting.

  • wire_throttle(ms, leading): Fires at most every ms milliseconds while the event is active.

  • wire_debounce(ms): Waits until the user pauses for ms milliseconds before firing.

When a wire carries no timing, irid applies a per-event default keyed on the DOM event name: input → wire_debounce(200) (typing produces a flood of intermediate values); the high-frequency continuous streams (mousemove, pointermove, touchmove, drag, dragover, scroll, wheel, resize) → wire_throttle(100) (paced "latest position" stream, with the derived coalesce = TRUE keeping it from outrunning the server); every other event → wire_immediate(). Explicit timing always wins over the default.

Backpressure (coalesce)

coalesce is universal across timing modes, so it lives on the carrier, not in the shapes. When TRUE, dispatch gates on server-idle state so events never queue faster than the server can process them. When NULL (the default), it derives from the timing mode: FALSE for wire_immediate(), TRUE for wire_throttle() / wire_debounce().

DOM listener options

wire_dom_opts() bundles the DOM-only listener flags. It is legal only where the event is backed by a real DOM listener (a plain tag, a custom element emitting cancelable events); placing it on a widget-emitted event errors. Whether prevent_default has any effect further depends on the event being cancelable — a runtime fact.

filter is a JavaScript expression string evaluated client-side with the DOM event object bound to e. When it evaluates falsy the event is dropped entirely — no prevent_default/stop_propagation, no server round-trip — so a handler that only cares about some events never floods the server with the rest. For example, an onKeyDown that acts only on Enter takes filter = "e.key === 'Enter'".

The event object

The event argument passed to handlers is a list containing all primitive-valued properties (string, numeric, logical) from the browser event object, plus these element properties:

value

The element's current value (character).

valueAsNumber

Numeric value of the element, or NA if the input is empty or non-numeric (e.g. a blank text box). Useful for range and number inputs.

checked

Logical, for checkbox and radio inputs.

Keyboard events additionally include key, code, ctrlKey, shiftKey, altKey, and metaKey.