DEV Community: Jon Nyman

_action: Declarative Event Handlers in an Attribute

Jon Nyman — Thu, 25 Jun 2026 04:08:28 +0000

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:

"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.
"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.

HTML Traits

Jon Nyman — Wed, 06 Aug 2025 05:18:36 +0000

Introduction

Imagine you want to add multiple interactive behaviors to a single HTML element—maybe an auto-expanding textarea that also validates character limits. With traditional web components, you'd end up with nested wrapper elements cluttering your markup, or you'd be limited to Safari's refusal to support built-in web components.

What if you could simply write <textarea traits="elastic character-limit"> and be done?

HTML Traits is a lightweight JavaScript library that makes this possible. It adds multiple behaviors to existing HTML elements through a simple traits attribute, giving you clean, composable functionality without the wrapper element overhead.

While built-in web components offer progressive enhancement through the is attribute, they come with significant limitations: Safari doesn't support them, you can only add one behavior per element, and behaviors are tied to specific element types. Regular web components solve some of these issues but force you to wrap your semantic HTML in unnecessary container elements.

HTML Traits

Enter html-traits. This little library
makes it so you can add multiple behaviors to a single element. It makes it so
you don't need nesting of elements. You just add an attribute. No need for
definitions to be defined with a dash. Some advantages are:

Composition over inheritance.
Multiple traits to one element.
Ordered traits.
Built for progressive enhancement.
No need for extra elements on your page just to get new runtime behavior.
Cleaner HTML.
No need to reimplement native element behavior as you just keep the original element.
Use native HTML for your elements rather than making everything custom and needing to learn custom APIs.
If you would like to use inheritance for helper functions that you use across all your traits it is easy to do so. Although composition over inheritance is desirable sometimes inheritance is the best solution.

A use case of this pattern could be a textarea element. We would like it to
automatically expand as you type. The old way, using web components, would be to
do this:

<elastic-textarea>
    <textarea></textarea>
</elastic-textarea>

But with HTML Traits:

<textarea traits="elastic-textarea"></textarea>

But now we would also like to make the textarea turn red, if there are more
than 250 characters. The old way:

<elastic-textarea>
    <character-limit data-character-limit="250">
        <textarea></textarea>
    </character-limit>
</elastic-textarea>

With HTML Traits:

<textarea traits="elastic-textarea character-limit" maxlength="250">
</textarea>

This makes making MPA-first applications much easier and cleaner with reusable
functionality written in a declarative way.

Limitations

HTML Traits is built specifically for progressive enhancement. It probably isn't
the right library for you if you want to go all into JS. It also doesn't work
with the Shadow DOM. Neither is it a full implementation of web components.
Although I'm trying to follow the same API as web components, it will never be a
true web component.

A working example

Here's a full implementation of the component character-limit.

class CharacterLimit {
    constructor(el) {
        if (!(el instanceof HTMLTextAreaElement)) {
            console.warn(`Expected an HTMLTextAreaElement, but received: ${el} for 'character-limit'.`);
            return
        }

        this.el = el
        this.maxLength = parseInt(this.el.getAttribute('maxlength'), 10);

        if (isNaN(this.maxLength)) {
            console.warn(`Invalid 'maxlength' attribute on element: ${this.el}. Expected a number.`);
            return
        }

        this.threshold = Math.floor(this.maxLength * 0.75);

        this.el.style.outlineColor = 'auto';
        el.addEventListener('input', this);
    }

    disconnectedCallback() {
        // Here we can clean up any resources or event listeners.
        // In this case we do not need to remove the event listener since it
        // will be automatically garbage collected.
        console.log(`CharacterLimit trait disconnected from element: ${this.el}`);
    }

    handleEvent(event) {
        this[event.type]?.(event);
    }

    input() {
        if (this.el.value.length < this.threshold) {
            this.el.style.outlineColor = 'auto';
            return;
        }

        if (this.el.value.length >= this.threshold) {
            this.el.style.outlineColor = 'orange';
        }

        if (this.el.value.length >= this.maxLength - 1) {
            this.el.style.outlineColor = 'red';
        }
    }

}

// Initialize the trait
window.defineTrait('character-limit', CharacterLimit);

And below is the HTML. Notice how the native attribute maxlength is used? It
is nice to only need to learn as little APIs as possible for a code base. Just
learn HTML and use what is already native! Also, notice in the code above, I
didn't need to implement cutting the text down, it was automatically implemented
by the browser with the attribute maxlength!

<head>
    <script type="module" src="./html-traits.js"></script>
    <script type="module" src="./character-limit.js"></script>
</head>

<body>
    <textarea traits="character-limit" maxlength="20"></textarea>
</body>

This was originally published on jnyman.com.