Distinguish between properties and attributes on custom elements

[Rich-Harris]

Describe the problem

One of the many reasons custom elements are a pain in the neck is that it's often rather ambiguous what's supposed to be an attribute and what's supposed to be a property. Some custom elements 'reflect' attributes back to properties and vice versa, but there's no universally agreed upon convention. If you're doing low-level DOM manipulation you can decide whether you want to do element.setAttribute(name, value) or element[name] = value, but everyone stopped writing code like that a decade ago.

It's a messy, flawed design, and different frameworks deal with it in different ways. Preact and Svelte both treat something as a property if prop in node, and an attribute otherwise. Vue does the same thing but additionally gives you a way to force something to be a prop (I don't think you can force something to be an attribute) with some interesting syntax choices:

---

---

Lit leans even harder into syntax, with ? and . and @ prefixes for boolean attributes, properties and event handlers respectively:

---

---

I think the explicit control is a good thing, but I think we can provide it more naturally.

Describe the proposed solution

#7925 and #12479 point the way. We're moving to a world in which quoted props on components are stringified:

<script>
  let object = { a: 1, b: 2, c: 3 };
</script>

<!-- in Svelte 6, this will mean `data="[object Object]"` -->
<Thing data="{object}" />

(The reason the quotes are ignored today is historical: in the distant past before Svelte editor extensions, when components were typically written in .html files, it avoided crazypants syntax highlighting.)

What if we did something similar for custom elements?

<foo-bar someprop={somevalue} someattribute="{someothervalue}"></foo-bar>

In other words if something is quoted, it's an attribute, otherwise it's a prop. We might need to change some Prettier defaults, but other than that this should be a relatively straightforward change. (I don't see any need to distinguish between 'boolean attributes' and properties like Lit does — they're all just properties.)

It is, of course, a breaking change. We would need to decide whether to do this in 5.0, or have a bunch of warnings and change it in 6.0. Ordinarily the conservative thing to do would be to delay the breaking change, but since it's not currently possible to differentiate properties and attributes I think there's a reasonable case for doing it sooner. As such I've given it a 5.0 milestone for now.

Importance

nice to have

[trueadm]

I actually love this a lot. Simplifies a ton of things along the way too.

[MarcusOtter]

And I assume to pass a string as a property the syntax would be this? (if I don't have it in a variable)

<foo-bar someprop={"my string here"}></foo-bar>

[ottomated]

My only qualm with this is that it seems hard to teach and unintuitive. Why does wrapping something in quotes mean that it's an attribute?

[henrikvilhelmberglund]

My only qualm with this is that it seems hard to teach and unintuitive. Why does wrapping something in quotes mean that it's an attribute?

Because HTML attributes use quotes style="color:red;". Imo makes perfect sense, if it has quotes outside of {} eg. "{}" it's an attribute (like normally in HTML), if it does not it's a prop.

[ottomated]

if it has quotes outside of {} eg. "{}" it's an attribute (like normally in HTML), if it does not it's a prop.

But in the case <foo-bar prop="foo" />, prop would be a property, right? What about in the case <foo-bar prop="{foo} a b" />?

To me, "{}" just signifies string interpolation, which is why I think that getting rid of the confusing legacy behavior is great – I don't like replacing it with a confusing new behavior.

It's kind of like if `${foo}` had a special behavior in javascript.

[Rich-Harris]

<foo-bar prop="foo" /> — prop is an attribute, because "foo". If you want a property, prop={"foo"}

<foo-bar prop="{foo} a b" /> — also an attribute

[ottomated]

What would the recommended way to do string interpolation for a property? <foo prop={`${foo} a b`} />?

[Rich-Harris]

Exactly, just like in normal JavaScript:

props = {
  prop: `${foo} a b`
};

[dummdidumm]

What about spreading properties? Does this always count as setting them as properties?

What about regular elements? I've seen (very few, rare) cases where people wanted things explicitly as an attribute or property.

As for timing: Since this is an uncommon case and can easily solved through e.g. an action, I'm in favor of taking our time with it and don't rush this into 5.0

[rChaoz]

How about boolean attributes? REPL

<input type="text" disabled={disabled}>
<!-- or -->
<input type="text" {disabled}>

Also, I believe it will be very easy to confuse the following, especially for new users:

<my-element a="{variable}" b={"text"} />

If we are going to make a breaking change, why not just force props to use a prefix, like :, or the same for attributes:

<my-element a={variable} :b="text" />

...and the same rules we knew so far about {} apply just the same.

Side now: I totally agree with arg="{variable}" converting the argument to a string, I wouldn't mind seeing that sooner than latter, but it would still be pretty breaking.

[Theo-Steiner]

I've been meaning to file an issue for this for ages, but never got around (totally not me bumping into this last year and promising to file an issue for it... 😅 )

Vue does the same thing but additionally gives you a way to force something to be a prop (I don't think you can force something to be an attribute) with some interesting syntax choices:

there's actually a syntax in vue for explicitly attributes as well: <my-foo bar.attr="passed as attribute"></my-foo> (although I don't think it is really documented anywhere?)

I think if it is set in quotes, it is an attribute, otherwise it's a property is a very elegant solution, but a few issues came to mind

• it's quite hard to spot
• it breaks with expecations of svelte 4 users
• having an equivalent to the prop shorthand <my-foo {bar}/> would be problematic
  • for bar="hidden", <my-foo "{bar}" /> will be translated to which one?
    a. <my-foo hidden="hidden" />
    b. <my-foo hidden />
• one shortcoming that came to mind:
  • since {"foo": "bar"} is equivalent to {foo: "bar"}, spreading can only ever set props
  • in vue, one could theoretically spread {"foo.attr": "bar"} vs {"foo": "bar"} to explicitly set a prop
    • (I don't think this is implemented in vue though)

Since this is an edge case, trading a less elegant/simple API for explicitness / programmatic control could be worth the tradeoff?
Maybe not reinventing the wheel, but picking either lit's .foo & .foo? or vue's foo.prop & foo.attr actually could be a good solution here, since people are already familiar with it and it wouldn't conflict with the existing way of doing things

[Rich-Harris]

What about spreading properties? Does this always count as setting them as properties?

There's basically three options:

1. {...stuff} spreads props
2. {...stuff} spreads attributes (or rather, does what set_attributes does on regular elements)
3. It uses the current heuristic

Given that a custom element has a finite number of props and a potentially infinite number of attributes, I would argue that (1) doesn't make sense — if you want to carve the props out of stuff, you can easily do that. That also results in the desired behaviour when spreading things like class.

I think (2) is the best option — it's consistent with how normal elements are handled, and easier to explain. We could augment it with a 'did you mean to do <foo-bar baz={stuff.baz} />?'-type warning, which we could also use to help people make sure they're using the right thing when not spreading. This would alleviate the concerns around discoverability.

How about boolean attributes?

For consistency I think we'd want to treat disabled="{disabled}" as an attribute in the context of a custom element (but this would raise the sort of runtime warning I just described, if the element in question implemented a disabled prop, or it was a property on HTMLElement.prototype like hidden).

This does create an inconsistency with <input disabled="{disabled}">, because we always treat that as a property (because there's no ambiguity when dealing with known properties of built-in elements). But I think we could separately consider compiler warnings in those cases, nudging people towards disabled={disabled} (or {disabled}) instead.

Maybe not reinventing the wheel, but picking either lit's .foo & .foo? or vue's foo.prop & foo.attr actually could be a good solution here

Thanks, I hate it 🤪

foo.prop and foo.attr are just terrible syntax IMHO — dot notation already means something in JS, and this looks like we're setting the attr property of the foo object or something. Really feels like a hasty compromise that was necessitated by constraints we don't share (like being able to read templates from HTML). .foo isn't quite as egregious, but it's still an ugly anomaly when it's only required for custom elements. Aesthetics matter!

I do think that if we started to nudge people towards a similar distinction for normal elements (by warning on quoted boolean properties like <input disabled="{disabled}">) it would soon feel like second nature, though I think the proposal still has value without that.