_action: Declarative Event Handlers in an Attribute

Introduction

In HTML Traits I went looking for a cleaner way to attach

behavior to an element than wrapping it in a custom element. Traits got me most

of the way there: composition over inheritance, multiple behaviors per element,

no wrapper soup. But once I started building real pages I noticed that the

majority of the behavior I wanted wasn't really a "component" at all. It was

just: when this changes, submit the form. Or: when this form submits, reset

it. Reaching for a class with a constructor and a lifecycle to express "call

this function on change" felt like too much ceremony.

So I wrote something even smaller. It lives in

_action.ts

and the whole thing is about 60 lines. Instead of defining a behavior and

registering it, you name a function and bind it to an event with an attribute:

<form _change=submit method=post action="?handler=editTeam">

    ...

</form>

When anything inside that form fires a change event, the function named

submit runs. That's it. No custom element, no trait definition, no wrapper.

How it works

There is a single set of delegated listeners on the document:

for (let event of ["click", "change", "submit"]) {

  doc.addEventListener(event, e => {

    let target = e.target

    let action = findAttr(target, event)

    if (!action) return

    handleCall(e, target, action)

  })

}

That ["click", "change", "submit"] list isn't special — it's just the set

this app happens to use. The mechanism works for any bubbling event, so if

you want input, keydown, focusout, or a custom event of your own, you add

its name to the list and you immediately get a matching _input / _keydown /

_focusout attribute to bind against. Nothing else changes.

For each event type it walks up from the target with closest([_${event}])

to find the nearest _click / _change / _submit attribute, with a fallback

to the element's owning form. The attribute's value is a space-separated list

of function names that live on window.app, and each one is called with a small

context object:

fn.call(null, { app: w.app, ev: e, target, el: target, form })

Because the listener is delegated at the document, it works for elements that

were swapped in later (this app morphs HTML in from the server), and because the

value can hold several names you get composition for free:

<input name=newPlayerName required _submit="reset clearAutoFocus">

Registering a handler is just hanging a function off window.app:

Object.assign(window.app, {

  reset: ({ form }) => form?.reset(),

  clearAutoFocus: ({ target }) => target.removeAttribute("autofocus"),

})

There is also a _load attribute, handled separately, for the "run this once

when the element appears" case. It fires on page load and again on hz:completed

(after server HTML is morphed in), then removes itself so it only runs once per

element:

The hz:completed event comes from

htmz-be, a small library I wrote for

morphing server HTML into the page. It was inspired by

htmz and

Datastar. It dispatches

hz:completed after a swap, which is the hook _action uses to re-run

_load handlers on freshly inserted elements.

function handleLoad() {

  for (let el of doc.querySelectorAll("[_load]")) {

    let action = el.getAttribute("_load")

    handleCall(new Event("load"), el, action)

    el.removeAttribute("_load")

  }

}

Most of the time it's this simple

In the soccer app the overwhelming majority of interactivity is a one-liner

attribute. Auto-submit a settings form as you edit it:

<form _change=submit method=post action="?handler=editTeam&teamId=${team.id}">

Reset the "add player" form after it submits, and drop the autofocus once

you've used it:

<form _submit=reset method=post action="?handler=addPlayer">

    <input name=newPlayerName required autofocus _submit=clearAutoFocus>

</form>

None of these needed a component, a lifecycle, or a definition. The function is

named, the attribute points at it, done.

When it gets more involved: the game timer

The interesting case is the live game timer. A <span> that ticks up every

second, can flash, can be paused (static), and ticks for several elements at

once on the page. Here _action is just the entry point — the _load

attribute instantiates a real class:

<span _load="gameTimer" data-total="${total}" data-static>00:00</span>

window.app.gameTimer = ({ el }) => {

  if (el._) return   // guard against double-init

  el._ = true

  new GameTimer(el)

}

The GameTimer class then does everything a stateful component does — but

notice it has to assemble its own lifecycle out of parts:

class GameTimer {

  constructor(el) {

    this.el = el

    this.interval = +(el.dataset.interval ?? 0) || 1e3

    document.addEventListener("hz:completed", this)

    window.app.disconnectWatcher?.(el, this)   // <-- borrowed teardown

    this.update(Date.now())

  }



  disconnectedCallback() {

    timer.remove(this)

    document.removeEventListener("hz:completed", this)

  }

  // ...

}

Two things stand out compared to the simple case:

1. 
   "Connected" is manual. _load is the moment of construction, and the
   el._ guard exists because, unlike a web component, nothing stops the same
   element from being initialized twice.


2. 
   "Disconnected" is borrowed. There's no native callback when the element
   leaves the DOM, so the app provides a disconnectWatcher — a single
   MutationObserver on document.body that calls disconnectedCallback() on
   registered instances when their node is removed. The timer leans on that to
   clean up its setInterval and its event listener.

This is the honest tradeoff: _action gives you next to nothing for free, so

when you do need real component semantics you reassemble them yourself from a

load hook, a guard flag, and a shared disconnect watcher. For one timer that's

fine. If half your page were stateful widgets, you'd feel the missing

lifecycle.

Comparing the three

All three solve the same underlying problem — attach behavior to HTML without

an SPA framework — but they sit at different points on the

simplicity-vs-encapsulation curve.

Web components

Pros:

• Real, browser-native lifecycle: connectedCallback,
  disconnectedCallback, attributeChangedCallback.


• Encapsulation, optional Shadow DOM, and a proper custom element registry.


• Standard — no library to ship.

Cons:

• Custom element names must contain a dash, and you generally wrap your
  semantic HTML in a non-semantic element.


• Built-in/customized elements (the is= form) aren't supported in Safari, and
  even there you get only one behavior per element.


• You re-learn and re-implement APIs that native elements already give you, and
  composing several behaviors means nesting several elements.

HTML Traits

Pros:

• Composition: traits="elastic-textarea character-limit", multiple,
  ordered behaviors on one element, no wrappers.


• Keeps the native element (and its native attributes like maxlength), so you
  learn less and reimplement nothing.


• Built for progressive enhancement; mirrors the web-component class API
  (constructor(el), disconnectedCallback) so it's familiar.

Cons:

• It's still "components": you define a class and register it for every
  behavior, which is more than some interactions deserve.


• A library you ship, and a partial reimplementation of web components — no
  Shadow DOM, never a true custom element.

_action

Pros:

• The smallest of the three (~60 lines, one set of delegated listeners). No
  per-element registration, no definitions — just name a function on
  window.app and point an attribute at it.


• Naturally composable (_submit="reset clearAutoFocus") and form-aware (it
  falls back to the owning form), which is exactly what MPA-style pages need.


• Works with server-morphed HTML out of the box because it's delegated at the
  document.


• Right-sized for the common case, which is "run this function on this event,"
  not "instantiate a stateful component."

Cons:

• No lifecycle by default. Initialization is a manual _load hook (plus a guard
  flag to avoid double-init), and teardown only exists if you opt into the
  shared disconnectWatcher.


• No encapsulation — every handler is a global on window.app, so naming is
  on you.


• It's event handlers, not components: for genuinely stateful widgets (the game
  timer) you end up rebuilding the very lifecycle that traits and web components
  hand you.

Which one when?

I think of it as a ladder, not a competition:

• 
  _action for the 90% that is "on this event, call this function" —
  auto-submit, reset, confirm, toggle a class. It's the default reach.


• 
  HTML Traits when a behavior is genuinely a reusable, stateful enhancement
  of a native element and you want clean composition without wrappers.


• 
  Web components when you need true encapsulation, Shadow DOM, or you're
  shipping a widget for other people's pages to consume.

The pattern I keep coming back to is that most "interactivity" on a server-driven

page isn't a component at all. _action lets me stop pretending it is.

This was originally posted on jnyman.com.