Skip to contents

Construct a widget — a wrapper for an arbitrary JavaScript library

Source: R/widget.R
IridWidget.Rd

IridWidget() is the third irid process-tags citizen (alongside control-flow nodes and Output). It emits a container element plus an init record that mount turns into a widget-init op. The client's irid.defineWidget("<name>", factory) registration is looked up by name and called once per mount. The factory may return its {update, destroy} handle directly or a Promise of it — make it async and await whatever its construction needs first (a script-tag library global, an ESM import, a WASM init). irid buffers updates during the wait and disposes cleanly on a teardown mid-construction. See the JS-side API in ARCHITECTURE.md.

Usage

IridWidget(
  name,
  props = list(),
  events = list(),
  deps = NULL,
  container = NULL
)

Arguments

name

Widget registry name, matching a JS-side irid.defineWidget("<name>", ...) call. Required, non-empty character scalar.

props

Named list of props. Callable values are two-way-capable bindings; non-callable values are init-only constants. NULL entries are forwarded to JS as null (not dropped). Wrap a value in wire() to tune its write-back timing.

events

Named list of notifications (client → server), keyed by wire event name. Each value is a handler, a wire(), or NULL (dropped). dom_opts is not allowed.

deps

Optional html_dependency or list of them. Required for any widget whose JS isn't already loaded by some other means.

container

Optional shiny.tag for the wrapper element. Defaults to tags$div(). irid sets id and data-irid-widget automatically. Configure any DOM events on the container by wrapping their handlers in wire() on the container directly.

Value

A irid widget construct with class irid_widget.

Details

Props are two-way-capable by default, exactly like DOM value / checked. A callable prop (reactiveVal, store leaf, reactiveProxy, ...) reads inbound to the widget (server → client, routed to the factory's update(key, value) hook) and accepts write-back: when the widget JS calls setProp(key, value), irid writes the value through the bound reactive (gated by writability — a read-only reactive's write is dropped and the canonical value is snapped back). Whether a prop is actually two-way depends on whether the widget JS pushes through setProp; the snap-back machinery is latent until it does. A non-callable prop rides in the init message as a constant and is never re-sent.

Wrap a prop in wire() only to tune its round-trip timing (content = wire(content, wire_debounce(200))) — never to enable or disable two-way. To react to a prop's change, observe the bound reactive or pass a reactiveProxy; a bound prop is not also handled.

events carries genuine notifications the widget emits that correspond to no prop (e.g. cursor-changed). Keys are the wire event names the widget JS passes to sendEvent() (lowercase kebab-case by web CustomEvent convention). Each value is a handler or a wire() (to tune timing); NULL entries are dropped so optional handlers forward declaratively. dom_opts is illegal on a widget event.