[TPAC Prep] Customized Built-in Elements: Current Status and Alternatives

[colepeters]

This report summarizes the current status of the customized built-in elements spec, its uses cases, suggested alternatives, and current outlook.

This report does not touch on issues relating to Form Associated Custom Elements or shadow DOM implementations, as other members are currently researching those areas independently.

Customized Built-in Elements

• Spec: https://html.spec.whatwg.org/multipage/custom-elements.html#customized-built-in-element
• Example: https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-customized-builtin-example
• Status:
  • Shipped in Blink and Gecko
  • Blocked in WebKit (see Customized built-in elements WebKit/standards-positions#97)

Use cases

1. Creating custom child elements within elements with strict permitted content

Many HTML elements (table, picture, video, ul, ol, etc.) are strictly limited in terms of what types of elements can be used as child content (defined as ‘permitted content’). For example, a table can only contain caption, colgroup, thead, tbody or tr, and tfoot elements. Similarly, the picture element can only contain one or more source elements and a fallback img element.

Some of these elements (e.g. ol/ul, table) may render unpermitted content (e.g. ol > p > li), but other elements (such as picture) will not. For example, the structure picture > div > source will not render the srcset specified on source, since source must be a direct child of picture.

Thus, if an author wishes to create a custom element to be used within one of these parent elements, customized built-in elements are the only way to do so while producing valid HTML structures and functional outcomes.

Example: sortable table

Consider a table which can be sorted in ascending or descending order via interactive column headers. Since the th elements themselves would need to be updated with the relevant aria-sort attributes whenever the active sort changes (and we would likely want to update the styling of the th elements themselves to visually indicate the active sort mechanism), we want to expose a custom th element to encapsulate this functionality.

<table>
  <thead>
    <tr>
      <custom-th>First Name</custom-th>
      <custom-th>Last Name</custom-th>
      <custom-th>Age</custom-th>
    </tr>
  </thead>
  …
</table>

However, since the above example uses autonomous custom elements for the custom-th element (even if it may internally wrap a th element), and because table and its sub elements are strict in which HTML elements are considered permitted content, this would produce semantically incorrect and invalid HTML.

The solution would be to use a customized built-in element, whereby the built-in th element is extended to handle this additional functionality while maintaining semantically correct and valid HTML.

<table>
  <thead>
    <tr>
      <th is='custom-th'>First Name</th>
      <th is='custom-th'>Last Name</th>
      <th is='custom-th'>Age</th>
    </tr>
  </thead>
  …
</table>

At present, however, it is impossible to ship this implementation to all users of evergreen web browsers, as WebKit has declined to implement the customized built-in elements spec (see status section above). We do not consider polyfilling an option as this can be fragile and results in degraded performance for WebKit end users, who make up a significant portion of global web traffic. Thus, patterns such as this example (and any other pattern in which elements with strictly permitted contents might be combined with custom elements) are effectively blocked at present.

2. Extending a built-in element’s behaviour

Extending a built-in element’s behaviour can be desirable even when that element does not need to be contained within a parent with strict permitted contents. This web.dev article contains two such examples — adding a ripple effect to a button, and extending the img element to include built in transformations.

The above examples could in theory be made possible by wrapping the button and img elements with an autonomous custom element, however it would result in unnecessarily nested HTML and a level of indirection that is less than desirable.

Potential alternatives

In a comment from July of 2023 on the issue stating WebKit’s position on the customized built-in elements spec, WebKit reviewer Ryosuke Niwa cited the following proposals as alternatives:

• Element Custom Enhancements, also known as Custom Attributes and Custom Properties (Custom Attributes and Element Enhancements have been implemented as third party libraries by Lume)
• Element Behaviours (however, this issue was closed by another WebKit contributor in 2018 and has not had active discussion since 2019)

Outlook

At present, Blink and Gecko’s support for the Custom Attributes/Element Enhancements proposals is unknown (which is understandable, given they’ve shipped the customized built-in elements spec). At the same time, WebKit’s official position and prioritization for implementing these proposals is also unknown. This impasse paints a frustrating picture for complete cross browser support for authors wanting to extend built-in elements with custom functionality and behaviour.

As can be seen from the GitHub issue discussing WebKit’s position on the customized built-in elements spec, a great many authors are eager for a solution to this challenge. This may also negatively impact end users, who may be served substandard implementations (via polyfills or inconsistent functionality) until viable solutions are available to authors on all modern web clients. Decisive collective action is needed from browser vendors and other interested parties to collaborate on and resolve this roadblock as soon as possible.

[Westbrook]

Consider a table which can be sorted in ascending or descending order via interactive column headers. Since the th elements themselves would need to be updated with the relevant aria-sort attributes whenever the active sort changes (and we would likely want to update the styling of the th elements themselves to visually indicate the active sort mechanism), we want to expose a custom th element to encapsulate this functionality.

Would love to get more in-depth info on why you'd count this as being true, especially when applied to customized built-ins:

• yes, the aria-sort needs to be added, but what sort of API on a custom element would be more direct or capable than just changing that value directly?
• sure, custom styles for that state might be appropriate, but you can't hang a shadow root on a th, how would you expect to style that content?

Are you maybe not asking for customized built-ins but instead for a change to the interpreter that allowed autonomous custom elements within <table> tags? Would such a thing need to also have some form of "Table-associated Element" API?

Maybe the above context, post interpreter changes, would be where element behaviors would come into play? <custom-th> behaved like a th...do any of the conversations in this area discuss decomposing native functionality (e.g. <label> or <option> or similar, too) for use by a developer of custom elements?

[colepeters]

yes, the aria-sort needs to be added, but what sort of API on a custom element would be more direct or capable than just changing that value directly?

I would want to upgrade th to be focusable + clickable, and add an event listener which would handle updating the aria-sort accordingly. I've done similar things imperatively via DOM APIs already, but being able to do this via customized built ins rather than one off scripts would make this all much more encapsulated, portable, etc.

sure, custom styles for that state might be appropriate, but you can't hang a shadow root on a th, how would you expect to style that content?

No need for shadow DOM. Depending on the implementation of the markup, custom-th or [is="custom-th"] CSS selectors work great.

Are you maybe not asking for customized built-ins but instead for a change to the interpreter that allowed autonomous custom elements within <table> tags? Would such a thing need to also have some form of "Table-associated Element" API?

I definitely don't want to complicate things further with another 'associated elements' API — if we need to have Table Associated Custom Elements, then we'd also need Picture Associated Custom Elements, List Associated Custom Elements, etc 😅

Updating the interpreter to make it possible to map a custom element to a built in element's semantics and functionality would be great — but that's exactly what we get with customized built-in elements (or, theoretically, the ability to attach custom attributes/behaviours to built in elements). This is why it kills me that that the custom built ins spec is getting blocked by WebKit.

Maybe the above context, post interpreter changes, would be where element behaviors would come into play? behaved like a th...do any of the conversations in this area discuss decomposing native functionality (e.g. <label> or <option> or similar, too) for use by a developer of custom elements?

I'm not clear on which discussions you mean — could you link me? :)

[Westbrook]

I'm not clear on which discussions you mean — could you link me? :)

I've not spent any time with the alternative APIs, so I don't know where such a thing would belong. Including it in the convo was just the first reaction that I had. Maybe it could go in one of these?

• Custom Property + 0 or more Custom Attributes => Custom Enhancement WICG/webcomponents#1000 (Custom Attributes and Element Enhancements have been implemented as third party libraries by Lume)
• Element Behaviors, and the has="" attribute. A useful alternative to Custom Elements in many cases! WICG/webcomponents#727 (however, this issue was closed by another WebKit contributor in 2018 and has not had active discussion since 2019)

No need for shadow DOM. Depending on the implementation of the markup, custom-th or [is="custom-th"] CSS selectors work great.

If so, styling needs here don't care whether the element is a customized built-in or not, right? Might be more impactful not to include them.

I would want to upgrade th to be focusable + clickable, and add an event listener which would handle updating the aria-sort accordingly. I've done similar things imperatively via DOM APIs already, but being able to do this via customized built-ins rather than one-off scripts would make this all much more encapsulated, portable, etc.

This is the juicy part of your need here that is not included in the OP.

It also asks a bunch of questions that I wonder if are answered in either the existing implementation of customized built-ins or any of the alternative proposals:

• Can an element hold both the columnheader or rowheader AS WELL AS a button role (in order for things to be focusable/clickable)?
• People already want customized built-ins because mimicking the focus/click/Enter/Space/etc is quite a lot. Would you want to build all of that into a th or would it be better to build that into a new element that owned the "behaviors" or "attributes" of both of its forebearers?
• The above point could be addressed in a shadow DOM context, have a slot for the accessible/readable content and then add buttons, etc. in the shadow DOM, but are there other paths that don't require the management of applied content (from the user) and implied content (from the custom element) in user space?
  • open reading of Open stylable shadow roots could point to that
• What's practically the difference between a customized built-in th and a table decorating element that manages all of this?

[colepeters]

I've not spent any time with the alternative APIs, so I don't know where such a thing would belong. Including it in the convo was just the first reaction that I had.

Sorry, I think I misread your initial question on this. Will investigate!

If so, styling needs here don't care whether the element is a customized built-in or not, right? Might be more impactful not to include them.

Fair, yup!

Can an element hold both the columnheader or rowheader AS WELL AS a button role (in order for things to be focusable/clickable)?

Good question. You can define multiple roles but that's intended to be used as a list of fallbacks rather than a combinatory role. Likely the better option would be to package this up as a th > button structure. In which case I may need to come up with a more concise use case than this, as I don't want to lead with a use case that requires too much drilling down. Will think on this.

People already want customized built-ins because mimicking the focus/click/Enter/Space/etc is quite a lot.

That's one use case for sure! But I also think leveraging existing element semantics and behaviours is important. I'll work to write an example that touches on this.

What's practically the difference between a customized built-in th and a table decorating element that manages all of this?

I'd say it's that a 'table decorating element' — presuming it's an autonomous custom element — doesn't carry any semantic meaning to the client and thus screen readers, document parsers, etc. Which is why being able to extend elements that already have those semantics is useful imo! :)

[Westbrook]

I'd say it's that a 'table decorating element'

Just to make sure we're talking about that same thing on this, I imagine:

<table-decorating-element>
  <table>
    <thead>
      <tr>
        <th>First Name</th>
        <th>Last Name</th>
        <th>Age</th>
      </tr>
    </thead>
    …
  </table>
</table-decorating-element>

While the decorating element has no semantic value, the content still has all the same semantic value it would otherwise with a single point of enhancement. Not to say it solves the situation, but is an important alternative to clarify the pros/cons of in a conversation like this one.

Looking forward to seeing what you come up with next!!

[colepeters]

Ahh I see, gotcha! Yeah, perhaps something I neglected to mention in my initial text is the idea of keeping elements composable, so that individual components can be imported and used independently. I'll be sure to call that out along w/ other revisions.

[colepeters]

Closing in prep for a replacement report, which I'll submit this week!