Proposal: Custom attributes for all elements, enhancements for more complex use cases

[LeaVerou]

This proposal introduces an API for defining custom attributes for both built-ins and custom elements, and design discussion for an API that can be used to define more complex enhancements that involve multiple attributes, methods, JS-only properties etc.

This came out of the TPAC extending built-ins breakout, and some follow-up discussions with @keithamus.

Defining attributes: The Attribute class

Use cases

• Augmenting existing elements (either built-ins or custom elements) with custom attributes that trigger custom behaviors
• Easier definition of a web component's own attributes, as this automatically takes care of property-attribute reflection, typing, default values etc, one of the biggest pain points of defining WCs without helpers

Prior art

• Original custom attributes proposal (naming only)
• @lume's custom attributes proposal
• LitElement properties
• VueJS props

Needs

• Lifecycle hooks: connected, disconnected, changed
• Default values
• Optional typing

API sketch

• Subclasses that extend a base Attribute class
• Static HTMLElement.attributeRegistry property which is an AttributeRegistry object. Attributes can be registered generically on HTMLElement to be available everywhere, or on specific classes (built-in or custom element classes).
  • For non custom elements, attribute names MUST contain a hyphen and not match a blacklist (aria-*, SVG attributes etc). Or maybe this should be a validation restriction, and not actually enforced by the API?
• Attribute should extend EventTarget so that authors can dispatch events on it.

Definition:

class ListAttribute extends Attribute {
	ownerElement; // element this is attached to
	value; // current value

	connectedCallback() { /* ... */ }

	disconnectedCallback() { /* ... */ }

	// Called whenever the attribute's value changes
	changedCallback() { /* ... */ }

	static dataType = AttributeType.IDREF;
	
	// Optional default value
	static defaultValue = null;
}

Usage on built-ins or existing custom elements:

HTMLInputElement.attributeRegistry.define("ac-list", ListAttribute);

An optional options dictionary allows customizing the registration, such as:

• propertyName to override the automatic camelCase conversion

MyInput.attributeRegistry.define("ac-list", ListAttribute, {
	propertyName: "autocompleteList",
});

Usage on new custom elements:

class MyInput extends HTMLElement {
	...
}

MyInput.attributeRegistry.define("ac-list", ListAttribute);
MyInput.attributeRegistry.define("value", class ValueAttribute extends Attribute {
	dataType = AttributeType.NUMBER;
	defaultValue = 0;
});

We could also add a new static attributes property as syntactic sugar to simplify the code needed and keep the definition within the class:

class MyInput extends HTMLElement {
	// Or maybe an array?
	static attributes = {
		"ac-list": ListAttribute,

		// Creates a suitable Attribute subclass behind the scenes:
		value: { dataType: AttributeType.NUMBER, defaultValue: 0 }
	}
}

Types

In v0 types could only be predefined AttributeType objects, in the future these should be constructible (all they need is a parse() and stringify() function, and maybe an optional defaultValue to act as a base default value).

Open Questions

• Should lifecycle hooks be called when the attribute is added, or when the element is connected/disconnected?

Complex Enhancements

Complex enhancements include:

• Multiple attributes (references to Attribute objects)
• Methods
• Properties and accessors (that don't correspond to attributes)

This can be fleshed out at a later time, since Attribute already deals with a lot of use cases. That could give us time to get more data about what is needed.

Prior art

• Element Behaviors
• Element custom enhancements

Needs & Design discussion

Referencing: How to associate enhancements with elements?

Element behaviors use a has attribute that takes a list of identifiers, and that is totally a viable path. The downside of this is that it introduces noise, and potential for error. E.g. imagine implementing a language like VueJS in this way, one would need to use has in addition to any v-* attribute, and would inevitably forget.

Associating enhancements with a selector would probably afford maximum flexibility and allows the association to happen implicitly (e.g. for an Enhancement implementing htmx, the "activation selector" could be [hx-get], [hx-post], [hx-swap], ..., without an additional has="htmx" being required eveyrwhere that these attributes are used.

Imperative association could allow us to explore functionality without committing to a particular declarative scheme. That way, individual attributes can still automatically activate behaviors, though it's a bit clunky:

class MyAttribute extends Attribute {
	connectedCallback () {
		this.ownerElement.behaviors.add(Htmx);
	}

	disconnectedCallback () {
		let hasOthers = this.ownerElement.getAttributeNames().some(n => n.startsWith("hx-");
		if (!hasOthers) this.ownerElement.behaviors.delete(Htmx);
	}
}

Flexibility

Should enhancements allow the same separation of names and functionality as custom elements and attributes? Given that they include multiple attributes, how would the association happen? I'm leaning towards that they'd also name the attributes they are including (since they are naming properties, methods etc already anyway).

// Should have the same syntax as HTMLElement.attributes above
attributes: {
	"v-if": VIf
	"v-else": VElse,
	"v-on": { value: VOn, propertyName: "vOnEvent" }
	...
}

List of use cases

I have been maintaining a list of use cases that I periodically add to here, I will edit this periodically to import it:

Use cases for custom attributes

• Emulating native functionality like…
  • datalist for autocomplete
  • title attribute for tooltips
  • Popover API
  • Invokers
• format attribute on <time> , <data> for presenting data with custom formats
• Form controls
  • Custom form validation
  • Show/hide password
  • Checkboxes
    • Designate a checkbox as an aggregate checkbox for checkboxes with a given name
  • Text inputs
    • Specific format, e.g. currency, measurement, 5-digit code, etc
  • <button>
    • <button href>
• General
  • Add icon (prefix="icon-name" /suffix="icon-name" )
  • Skeleton (e.g. <p loading-placeholder="3 sentences"> )
  • Tooltip
  • Data binding
  • Highlight matches within (e.g. highlight="foobar" )
  • removable (adds X button that removes the element and fires a suitable event)
• Tables
  • <table sortable>
  • <td value> to be used for filtering and sorting
• <pre>
  • <pre src>
  • <pre editable> for code editors (or any other element)
  • <pre normalize-whitespace>
• HTMLMediaElement (<audio> and <video> )
  • Custom toolbar
  • start-at="0:05"

[EisenbergEffect]

That was a fast turnaround....

There are a couple of things I like about this right off the bat:

• I like that this can be used to simplify attribute definition on custom elements.
• I like that this recognizes the problem of typing attributes and is even open to custom converters in the future.
• I like that this considers supporting a default value.
• I like that the programming model is pretty simple and harmonious with custom elements.

I agree on the need to hyphenate names, again matching the CE rules and the strict blocking of certain names altogether.

I need to think more about registration. That's the biggest open question for me. I think having registries on the individual types is interesting. I hadn't thought about doing it that way. I wonder how that will work with custom element registries, particularly WRT scoped registries. So, I wonder whether attribute registration should just be another API on the existing custom elements registry, so we can inherit all the work on scoping for attributes as well.

My personal preference...I don't particularly like using a "has" attribute vs. just using attribute names. It doesn't feel as "HTML-y" to me. That's not a deal breaker for me though.

I do think there should be a programmatic way to add and remove behaviors (and as a result, possibly callbacks for when that happens). I'm inspired a bit by Unity 3d, which has a generic scene graph with a behaviors system that is the mechanism for all node specialization. Behaviors are part of a collection and can be added, removed, searched, etc. This comes in handy if you want to build more complex systems of behaviors where one behavior looks for another and then if found, collaborates with it through its public API. You could imagine a custom drag/drop system working this way with custom attributes for draggables and drop targets, where the attributes locate one another and through their APIs coordinate the drag/drop.

Ok, that's just a few quick thoughts. I'm excited to see if we can make this happen!

[bahrus]

Thanks for the implicit feedback on my proposal. There are some nice ideas here I may steal if that's okay, with "attributions" (sorry for the bad pun) (and apologies for overlooking your original 2017 proposal, will add a link to that for sure). I remain unconvinced of this direction (but I will see if my reasons hold merit on reflection). It seems I am in a minority of one, but I will continue slogging along at my proposal, incorporating ideas such as these, in case we find a happy compromise.

For starters, it seems that the feedback is that my proposal is too complicated, so I will look for a better "on ramping" experience.

One concern:

// This also works:
MyInput.attributeRegistry.define("ac-list", ListAttribute, {
	propertyName: "autocompleteList" // if we want to override the default acList
});

This means that in order to register the attribute, then we need to wait for the MyInput class to be downloaded. But if we use whatever we call this thing-of-a-jiggy for doing cross cutting things (like binding during template instantiation, for example), I think that could be an issue.

I'm curious if you could provide insights on this question: When I look at this documentation, it seems that by default the "hooks" can apply to all elements by default. Likewise when I look at Vue and others (knockout.js) etc. My proposal was heavily influenced by what I see in industry (as that seems like a proven model?)

It seems that by default your proposal is deeply curtailing the developer's "reach" and I'm puzzled as to why? Is it parsing constraints?

I agree we want the developer to be able to curtail their own reach, but I'm a bit surprised that that is the direction this is taking?

[sorvell]

Thanks for writing this up so quickly! Some initial thoughts on this proposal only, still need to digest some of the referenced alternatives.

1. This is probably obvious but seems like it often comes up: all the capabilities described here are mostly possible in the platform today via MutationObserver and Object.defineProperties. Therefore, the goal here needs to be clear and is likely something like making these capabilities (1) more ergonomic, (2) perform better, (3) reliably baked in.

2. Experience with customElements and the scoped registries proposal suggests that scoping is a must and to avoid the pain custom elements has gone through, this feature shouldn't ship without it.

3. Custom Element attribute reflection is indeed annoying, but it's not clear if this feature would be directly applicable. Perhaps instead, there's a lower level seralization/deserialization primitive that could be used here and also with observedAttributes.

4. It's important to state clearly that the reason to use attributes is to make the augmented behavior declaratively configurable. While we (or at least I do) typically think of this as being synonymous with HTML, JSX is very popular and although it is html-like, it has the ability to set complex non-serializable data directly via properties. This suggests that basic version should support property setting. Here's a straw proposal: (1) use has to install a behavior (e.g. has="foo bar", (2) this makes a property ...DataSet (e.g. fooDataSet) available on the element and configurable via ...-data-X (e.g. foo-data-mood="happy"). Systems that set properties could then just set a property like e.g. fooDataSet.mood = 'happy'.

[LeaVerou]

@EisenbergEffect

need to think more about registration. That's the biggest open question for me. I think having registries on the individual types is interesting. I hadn't thought about doing it that way. I wonder how that will work with custom element registries, particularly WRT scoped registries. So, I wonder whether attribute registration should just be another API on the existing custom elements registry, so we can inherit all the work on scoping for attributes as well.

@sorvell

Experience with customElements and the scoped registries proposal suggests that scoping is a must and to avoid the pain custom elements has gone through, this feature shouldn't ship without it.

Hm. I need to understand the use cases more where scoping comes into play with attributes.

Attribute registries are scoped to element classes already. Is the use case having different attributes for the same element class if registered differently, in different registries? Is the use case adding an attribute to a built-in only when used within a WC's Shadow DOM, without affecting the built-in outside that?

FWIW making scoping part of the custom elements registry is also problematic: First because registration is often decoupled from the custom element definition, so that consumers can do the registration. If now consumers also have to register all the element's attributes, that is too much work on the consumer side, for little benefit, plus it would break DOM methods to read/write attributes.
Second, because one of the primary driving use cases is adding custom attributes to built-ins, which are not registered on any CustomElementRegistry.

---

@sorvell

Custom Element attribute reflection is indeed annoying, but it's not clear if this feature would be directly applicable.

How so? It's designed with that as a primary use case.

Perhaps instead, there's a lower level seralization/deserialization primitive that could be used here and also with observedAttributes.

If there is, even better! Though I suspect use cases for observedAttributes would drop very significantly once this is available.

This suggests that basic version should support property setting.

It …already does? In fact, it entirely automates it 🙂
Perhaps you mean properties that don't correspond to attributes (akin to LitElement's attribute: false)? I can definitely see use cases for that, the reason that wasn't included was that this is not that difficult already.

---

@bahrus

One concern:

// This also works:
MyInput.attributeRegistry.define("ac-list", ListAttribute, {
	propertyName: "autocompleteList" // if we want to override the default acList
});

This means that in order to register the attribute, then we need to wait for the MyInput class to be downloaded. But if we use whatever we call this thing-of-a-jiggy for doing cross cutting things (like binding during template instantiation, for example), I think that could be an issue.

Not necessarily, that's what customElements.whenDefined() is for.
Also, I think adding custom attributes to other custom elements, while important, is probably one of the least prominent use cases (compared to adding them to built-ins, and adding them to your own components).

I'm curious if you could provide insights on this question: When I look at this documentation, it seems that by default the "hooks" can apply to all elements by default. Likewise when I look at Vue and others (knockout.js) etc. My proposal was heavily influenced by what I see in industry (as that seems like a proven model?)

It seems that by default your proposal is deeply curtailing the developer's "reach" and I'm puzzled as to why? Is it parsing constraints?

I agree we want the developer to be able to curtail their own reach, but I'm a bit surprised that that is the direction this is taking?

I …don't understand what you're asking here at all. 🤷🏽‍♀️ What's the relevance of Mavo hooks and Vue plugins? What is curtailing what developer reach? 🤔

[bahrus]

@LeaVerou

I agree very much with two things you have said:

Also, I think adding custom attributes to other custom elements, while important, is probably one of the least prominent use cases (compared to adding them to built-ins, and adding them to your own components).

and I try to abide by the principal you've brought up -- about making simple or common things, easy to do, while not making complex things impossible. So, thinking about it last night, here's my simple use case, and I will add to it my proposed solution to that simple case, that I think typifies the "common" use cases in my mind:

Say all you need to do is to create an isolated behavior/enhancement/hook/whatever associated with an attribute, say "log-to-console" anytime the user clicks on elements adorned with that attribute, where we can specify the message. Here's how that would be done with the custom enhancements proposal:

customEnhancements.define('log-to-console', class extends ElementEnhancement{
    attachedCallback(enhancedElement: Element){
        const msg = enhancedElement.getAttribute('log-to-console');
        enhancedElement.addEventListener('click', e => {
            console.log(msg);
        });
    }
});

<svg log-to-console="clicked on an svg"></svg>
    ...
<div log-to-console="clicked on a div"></div>

...

<some-custom-element enh-log-to-console="clicked on some custom element"></some-custom-element>

Done!

If your proposed alternative is as simple, then my question to you regarding vue and mavo was truly out of left field and irrevelant. (I really do want to peg my hopes on someone else's proposal, not my own, so hoping you can address this concern I have). How would your proposal solve this? How many lines of code would be required to cover all the DOM elements?

@sorvell , you had me in complete agreement until you proposed the has option -- it seems to me solving the problem above
with the has option would require introducing two attributes (one of them data-) which doubles the chances of conflicts with other developers.

And can we go to teams like HTMX and Alpine and Wordpress and say "sorry, to get the platform's blessings, what you've been doing is wrong -- you need two attributes to solve this problem, which I know is more complicated, few if anyone has or is doing that, and increases the chances of naming conflicts, but the benefits are..."

And that's where I'm drawing a blank, without attempting to mind read, and probably getting the benefits wrong. Could you explain what I'm missing?

[LeaVerou]

@bahrus

Say all you need to do is to create an isolated behavior/enhancement/hook/whatever associated with an attribute, say "log-to-console" anytime the user clicks on elements adorned with that attribute, where we can specify the message.

Sure, here you go:

class LogAttribute extends Attribute {
	connectedCallback() {
		this.ownerElement.addEventListener("click", e => console.log(this.value));
	}
};

HTMLElement.attributeRegistry.define("log-to-console", LogAttribute);

Roughly the same amount of code I believe.

Note that because SVG elements do not inherit from HTMLElement, it will not work for SVG elements, but this is a matter of definition. I defined it this way since custom elements also inherit from HTMLElement. If adding attributes to SVG elements is desirable, it's trivial to hang attributeRegistry off of Element instead.

Here's how that would be done with the custom enhancements proposal:

Btw your code will log the old message even if the attribute changes (this is easily fixable by moving the msg declaration in the event listener).

When does attachedCallback fire? If it can fire multiple times for an element (e.g. if it's removed and re-added to the DOM multiple times), you will have multiple listeners, and thus log the message multiple times. Depending on how connectedCallback() works in Attribute, my example above may have the same issue, but I opted to keep it as close to your example as possible.

And can we go to teams like HTMX and Alpine and Wordpress and say "sorry, to get the platform's blessings, what you've been doing is wrong -- you need two attributes to solve this problem, which I know is more complicated, few if anyone has or is doing that, and increases the chances of naming conflicts, but the benefits are..."

+1 to that.

[bahrus]

You are correct, in your observations, all good points. I literally wanted to look at the simplest requirement to compare, which you've done in spades. Thanks!

You've easily convinced me that I was wrong, I misread what you are proposing, (I guess I was thrown by the HTMLInput.attributeRegistry.define, but on rereading what you wrote, I see what I missed). I hope you will address the more "complex" things I'm after (the ability for all these solutions to work well together) as the proposal progresses, and I feel a burden lifting from my shoulders as we speak!

[bahrus]

Hi @LeaVerou ,

I for one vote overwhelmingly to support svg (I was proposing that by extending "ElementEnhancement"), and I think it is up there in the top complaints / limitations for custom elements. So unless there's a solid reason not to, why wouldn't we?

(mis)reading your proposal further (apologies in advance):

Associating enhancements with a selector would probably afford maximum flexibility and allows the association to happen implicitly.

I'm getting a little lost here. Is your proposal heading in the direction of allowing each custom attribute to "opt-in" to be a behavior? Is that why you are considering the "has" attribute? Is basing access to the name of the behavior based either literally on the custom attribute, or the camelCase string problematic?

Either way, I'm not following some of the discussion (apologies, again), but have you yet settled on how third party vendors can access the behavior, what that looks like (and how to make that seamless), or is that a work in progress? Are attributes required to enhance an element? If so, why?

Feel free not to answer, just wanted to convey what I'm looking for to be 100% satisfied, and what I'm finding difficult to follow.

[LeaVerou]

Hi @LeaVerou ,

I for one vote overwhelmingly to support svg (I was proposing that by extending "ElementEnhancement"), and I think it is up there in the top complaints / limitations for custom elements. So unless there's a solid reason not to, why wouldn't we?

I'm with you on that one!

(mis)reading your proposal further (apologies in advance):

Associating enhancements with a selector would probably afford maximum flexibility and allows the association to happen implicitly.

I'm getting a little lost here. Is your proposal heading in the direction of allowing each custom attribute to "opt-in" to be a behavior?

You're right that as currently described, each custom attribute would be "opting-in", but also note that you could e.g. activate the behavior for the entire subtree the attribute is on (e.g. imagine a declarative version of Vue where the selector would be [v-app], [v-app] *.
However, in the spirit of making common things easy, I think it would make sense to define a default (if no selector is provided) that simply makes all specified attributes "activate" the behavior.
Note that this cannot be the only activation mechanism, as then attributes would be required (or imperative association).

Is that why you are considering the "has" attribute?

I'm listing two potential association schemes. I don't think we should go with has, for the reasons I listed.

Is basing access to the name of the behavior based either literally on the custom attribute, or the camelCase string problematic?

Not 100% sure I fully understand what you're saying here, but perhaps the default I'm proposing above satisfies that?

Either way, I'm not following some of the discussion (apologies, again), but have you yet settled on how third party vendors can access the behavior, what that looks like (and how to make that seamless), or is that a work in progress?

Not 100% sure I understand what you're asking here either, but since these are regular objects (most likely classes, but I could see plain literals working too) you can just export them in the usual way. If that doesn't answer your question, I think some more specific use cases could help me understand it better.

Are attributes required to enhance an element? If so, why?

No, they are not.

Feel free not to answer, just wanted to convey what I'm looking for to be 100% satisfied, and what I'm finding difficult to follow.

This is great feedback on what I may not have explained sufficiently well, so please keep it coming!

[sorvell]

@LeaVerou

Hm. I need to understand the use cases more where scoping comes into play with attributes.

Unless I'm missing something, the basic scoping problem is the same for both custom elements and custom attributes.

The issue with custom elements is basically this: my-element-a might import and depend on fancy-list and my-element-b might import and depend on a different fancy-list. Custom elements are designed, in general, to have their details encapsulated but the dependence on fancy-list leaks since its existence is global.

The same issue could occur with my-element-a importing and depending on HTMLInputElement.attributeRegistry.define("ac-list", ListAttribute); and my-element-b importing and depending on a different ac-list attribute.

If there is, even better! Though I suspect use cases for observedAttributes would drop very significantly once this is available.

// Creates a suitable Attribute subclass behind the scenes:
value: { dataType: AttributeType.NUMBER, defaultValue: 0 }

The bit that isn't quite connecting with me is perhaps just not filled in yet. Having to configure an element's attributes' behavior via something other than the element class feels unnatural, but this part of the proposal may just need to be worked out more.

Perhaps you mean properties that don't correspond to attributes (akin to LitElement's attribute: false)?

There's 3 cases that I think are actually fairly common: (1) 2 way reflection: attribute <-> property, (2) 1 way reflection: attribute -> property, (3) property only.

• Case (2), reflecting a property value back to the attribute is useful for serialization and for triggering platform actions that depend on the attribute (maybe just styling in this case). It's also done for only some platform properties, e.g. not Input.value or Button.onclick.
• Case (3), no attribute is perhaps not something to encourage but it's done for some platform things like HTMLMediaElement.currentTime and is generally useful for data that just won't ever serialize. Even if it's simple to install via Object.defineProperty(someElementProto), it's probably good to include here so it's reliably baked in.

[sorvell]

Couple other points related to the basic design of the class:

1. I think the MVP lifecycle would include ownerConnected/DisconnectedCallback so that behavior can be triggered based on the element being "in use" in the DOM. Quick example: there's a data subscription attribute and the attribute needs to be able to disconnect from some system when the element is no longer used in the tree.
2. The one-to-one mapping between behavior enhancement and attribute name/value feels limiting/cumbersome. Contrived example:
   • <input has="happy sad bored" onhappy... onsad... onbored...> v.
   • <input has="moods" onhappy... onsad... onbored...>

[bahrus]

@sorvell , so I think you are advocating allowing one behavior to "own" multiple (non-data?) attributes.

Benefits I see:

1. This would allow for the values associated with the behavior to be "spread out", not scrunched into a JSON object.
2. It might be easier for the browser to "discover" the enhancements.
3. The names of the behaviors could be a single word.

Dangers:

1. I think the message on "namespacing" the attributes becomes cloudier -- more than one "owned" name associated with a package, basically. Maybe solvable with prefixes?
2. It still complicates simpler use cases (such as the log to console example), behaviors that only really expect to have one value throughout their lifespan.

Maybe that approach should be optional?

[smaug----]

Attribute should extend EventTarget so that authors can dispatch events on it

What does that mean? What is this Attribute interface? And who would add listeners to it?

[iteriani]

I wonder if in practice registering custom attributes like this ends up in a situation where it becomes impossible to DCE or move this code to late modules because it might end up being used somewhere. Any way of avoiding this ends up putting explicit imports somewhere, which may be unintuitive.

This problem probably happens even with this is="" approach too, so I guess this isn't really making anything worse