Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 39 ยท Custom Elements

Customized Built-in Elements

Extend native elements such as button, a and input with the is attribute. See how customized built-ins work, what they cannot do, and the Safari support gap.

Autonomous custom elements start from nothing: a blank HTMLElement. Sometimes that is wasteful. If you want a better button, you must recreate focus handling, keyboard activation, form participation and accessibility, all of which a real <button> already has. Customized built-in elements let you extend an existing element's class and keep everything it already does.

The syntax

You extend the specific element class, such as HTMLButtonElement, and tell define which tag it extends with a third argument.

JavaScript
class ConfirmButton extends HTMLButtonElement {
  connectedCallback() {
    this.addEventListener("click", this.#onClick);
  }
  #onClick = (event) => {
    if (!confirm("Are you sure?")) event.preventDefault();
  };
}
customElements.define("confirm-button", ConfirmButton, { extends: "button" });

You then use the built-in tag and name your element with the is attribute:

HTML
<button is="confirm-button">Delete</button>

You can also create it from script, either with document.createElement("button", { is: "confirm-button" }) or with new ConfirmButton().

Notice that the tag name here is the standard button. The hyphenated name only appears in is. Because the element is still a real <button>, it has the button role, receives focus, activates with Enter and Space, submits forms and supports disabled, with no extra work.

A working example

This example turns an ordinary <button> into one that shows a click count and disables itself after a limit. The runnable code relies on your browser supporting the feature, so it first checks.

A button that remembers clicks

In browsers that support the feature, the button counts and then disables itself with the built-in disabled property: you did not have to implement it. In Safari, which does not support is, the button remains an ordinary button and the sentence says it was not upgraded.

Which elements can you extend?

Any HTML element that has its own interface class: HTMLButtonElement, HTMLAnchorElement, HTMLInputElement, HTMLImageElement, HTMLParagraphElement, HTMLUListElement, and so on. Elements that share the generic HTMLElement interface (such as <section> or <span>) extend HTMLElement and use the extends option with the tag name:

JavaScript
class Banner extends HTMLElement { /* ... */ }
customElements.define("site-banner", Banner, { extends: "section" });

Limits to know

  1. No Shadow DOM on most built-ins. attachShadow is allowed only on a fixed list of tags (such as div, section, article, aside, header, footer, nav, main, p, span, blockquote, headings) and never on form controls like button or input. So customized built-ins are mostly about behavior, not private markup.
  2. Safari does not support them. WebKit's team declined to implement the feature. A customized built-in in Safari is just the plain element, so your code must degrade gracefully, or you must load a polyfill.
  3. Constructor rules still apply. Same restrictions as autonomous elements.
  4. Slots work only with a shadow root, so you cannot use <slot> on a customized <button>.

Autonomous vs customized: how to choose

Autonomous (<my-button>) Customized (<button is="my-button">)
Support All browsers Not in Safari
Built-in accessibility and form behavior You build it Inherited
Shadow DOM Always available Mostly unavailable
Fallback if script fails Unknown tag, shows its text A normal working element
Use for Complex widgets, design-system parts Light enhancements of native elements

The "graceful fallback" row is a real advantage of customized built-ins: with JavaScript off, a <a is="fancy-link"> is still a link.

If you need native form behavior in an autonomous element but cannot use is, there is another route: form-associated custom elements with ElementInternals, covered in the forms chapter. It works in Safari.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you use a customized built-in element in HTML?

    You keep the native tag and add the is attribute with your registered name.
  2. 2. Which third argument registers a customized built-in?

    define(name, Class, { extends: 'button' }) tells the registry which native tag it extends.
  3. 3. Which browser does not support customized built-in elements?

    WebKit has not implemented the is attribute for customized built-ins.
  4. 4. What is a main benefit of extending a built-in element?

    The element is still a real button or link, so focus, keyboard and form behavior come for free.

Summary

  • Customized built-ins extend a specific native class and use the is attribute.
  • Register with customElements.define(name, Class, { extends: "tag" }).
  • They inherit native behavior and degrade gracefully, but are unsupported in Safari.
  • Most of them cannot have a shadow root, so they enhance behavior rather than markup.
  • Choose autonomous elements for portable widgets and customized ones for light enhancements.

Next: Upgrading and whenDefined