Listen to Events#

Every state change starts somewhere. Usually that somewhere is the user. Event listeners respond to interactions, and they are the main cause of changes in component state.

Call on(target, type, handler) from the factory context with an explicit target element or Cell<E[]> collection:

defineComponent('my-component', ({ all, expose, first, host, on }) => {
  const buttons = all('button')
  const input = first('input')

  expose({ active: 0, value: '' })

  on(buttons, 'click', (_e, target) => {
    // Set 'active' signal to value of data-index attribute of button
    const index = parseInt(target.dataset.index ?? '0', 10)
    host.active = Number.isInteger(index) ? index : 0
  })
  // Set 'value' signal to value of input element
  on(input, 'change', () => ({ value: input.value }))
})

The handler receives (event, element). For Signal targets, element is the matched item from the collection. The handler can also return an object to batch-update multiple host properties at once:

on(button, 'click', () => ({
  count: host.count + 1,
  lastClicked: Date.now(),
}))

Event listeners are automatically removed when the component disconnects.

Synchronize State with Effects#

State changed. Now something in the DOM has to catch up. Effects do that work for you: watch(source, handler) re-runs the handler whenever the source changes, and nothing else.

watch('open', bindAttribute(host, 'open')) // set attribute from 'open' signal
watch('count', bindText(count))            // update text from 'count' signal
watch('isEven', bindClass(count, 'even'))  // toggle class from 'isEven' signal

The order of watch() calls does not matter.

bind* Helpers#

Most DOM updates are common operations: set text, toggle a class, show or hide. Le Truc ships a bind* helper for each, and every helper is a handler you can pass straight to watch():

Two of these deserve a second look.

bindAttribute() validates string values before writing them: event-handler attributes (on*) are rejected, and URL attributes must pass a safe-protocol allowlist. Violations throw — they are never silent.

bindState() toggles a custom state that CSS matches with :state(token). Unlike a class, a custom state belongs to the component; author code or a framework rewriting the host's class attribute cannot overwrite it.

bindAria() targets internals or a native element to drive ARIA reflection — a separate channel from content attributes, with its own no-mixing rules. See Accessibility for the full picture.

Bind Several Targets from One Source#

bindStyle(), bindAttribute(), bindAria(), bindClass(), bindProperty(), and bindState() each also accept an array of targets instead of a single one. Use this when one computed value drives several properties, attributes, ARIA properties, class tokens, object keys, or custom states at once — one watch() call instead of several:

watch(
  () => ({ '--gauge-color': color, '--gauge-degree': `${degree}deg` }),
  bindStyle(host, ['--gauge-color', '--gauge-degree']),
)

The array of targets is fixed where you call the helper. The handler you pass to watch() receives an object keyed by those targets. For bindStyle(), bindAttribute(), and bindAria(), a target missing from that object (or set to null/undefined) is cleared — removed from the style/attribute, or set to null for the ARIA reflection. bindClass() and bindState() toggle off the same way. bindProperty() is the exception: a missing key is left alone, not cleared, because arbitrary object properties have no "remove" operation.

Derive Inline with a Thunk#

Instead of a named signal, you can pass a thunk as the watch source to derive a value inline:

defineComponent('my-component', ({ expose, first, host, watch }) => {
  const count = first('.count')
  const double = first('.double')

  expose({ count: 0 })

  watch(() => !(host.count % 2), bindClass(count, 'even'))
  watch(() => String(host.count * 2), bindText(double))
})

Per-element Effects with each()#

A single watch() handles one source. When you have a Cell<E[]> collection and each element needs its own reactive effects, each(memo, callback) creates a per-element scope. Effects activate when elements enter the collection. They are disposed when elements leave:

defineComponent('module-carousel', ({ all, expose, host, watch }) => {
  const dots = all('button[role="tab"]')

  expose({ index: 0 })

  each(dots, dot => {
    watch(
      () => dot.dataset.index === String(host.index),
      selected => {
        dot.ariaSelected = String(selected)
        dot.tabIndex = selected ? 0 : -1
      },
    )
  })
})

The callback receives a single element. Inside the callback you can use the reactive helpers (watch(), on(), each(), pass()) to define effects.

Bidirectional Binding with Native Elements#

Some native elements (checkboxes, text inputs, selects) hold state in JS properties not reflected by HTML attributes at runtime. input.checked and input.value are the canonical examples. The attribute sets only the initial state. The property tracks the live state. To keep a signal in sync with a native element, you need to both read from it and write back to it.

The form-checkbox component shows this pattern in full:

defineComponent('form-checkbox', ({ expose, first, host, on, watch }) => {
  const checkbox = first('input[type="checkbox"]', 'Add a native checkbox.')

  expose({
    // Read initial checked state from the DOM property, not the attribute
    checked: checkbox.checked,
  })

  // Capture user interaction → update signal
  on(checkbox, 'change', () => ({ checked: checkbox.checked }))
  // Sync signal → drive native element property
  watch('checked', bindProperty(checkbox, 'checked'))
})

Three pieces work together:

1. checkbox.checked — initializes checked from the DOM property at setup time, picking up any server-rendered or pre-set state.
2. on(checkbox, 'change', ...) — returns { checked: checkbox.checked } to update the signal when the user interacts with the checkbox.
3. watch('checked', ...) — drives checkbox.checked = value whenever the signal changes, including when a parent component sets host.checked programmatically.

This creates a full cycle: DOM → signal → DOM, with the signal as the single source of truth.