Summary

  • The W3C’s first public Custom Elements draft appeared on 14 May 2013. A 2016 draft described class-based definitions, a registry, upgrades and lifecycle callbacks; a 2018 Note recorded the work’s incorporation into DOM and HTML specifications.
  • In the current HTML Standard, authors register definitions in a CustomElementRegistry. The browser matches and upgrades eligible elements, then runs reactions for events such as connection and observed attribute changes. The author supplies the behavior that makes the tag useful.

Imagine a newsroom that wants a <story-card> wherever a headline, picture and reading link should travel together. A plain unfamiliar tag can sit in markup, but the newsroom also wants the card to initialize itself, notice a change in one attribute and clean up when removed. It could write a separate script to patrol every card on every page. Or the browser could keep a registry of tags with instructions and call the right code when the elements’ lives change. Custom Elements took the second route.

The W3C First Public Working Draft of 14 May 2013 framed the ambition: authors could define new types of DOM elements in a document. Its early model associated a name and prototype with lifecycle callbacks. The details would change, but the political arrangement was already visible. The platform would control how a new tag entered the document’s ordinary element system; the author would decide what the tag did once it arrived.

The W3C Working Draft of 9 June 2016 shows a more familiar hiring desk. An author writes a class extending HTMLElement and registers it with customElements.define(). The draft’s example includes an element already in the document before its definition is registered. Registration upgrades the eligible in-document element. An unfamiliar tag can wait in markup until its instructions arrive; the browser then puts the matching instance to work.

The registry does more than attach a constructor to a word. It validates names and coordinates the timing of upgrades and reactions. A hyphen in an autonomous custom element’s name helps mark space reserved for author-defined tags. The author can declare observed attributes and provide attributeChangedCallback() to react when they change. connectedCallback() runs when an element becomes connected; disconnectedCallback() can handle departure. The browser schedules these lifecycle calls under its element-reaction rules. The card’s behavior stays with the card instead of being scattered across a script that searches the whole page.

That arrangement has a useful surprise. A tag’s markup may be present before its author’s code loads. The page can name a <story-card> and let the browser parse it; a later registration can upgrade matching elements. This is a practical answer to the timing of complex pages, where markup and component definitions do not always arrive in lockstep. The author still has to write careful code for initialization and repeated connection. The browser’s promise is to manage the identity and lifecycle hooks, not to design a good story card.

The stand-alone specification later moved. The W3C Working Group Note of 3 May 2018 says Custom Elements material was being incorporated into DOM, HTML and related specifications. The W3C publication history preserves the path from the 2013 first public draft through later working drafts to the 2018 transition. This is an archival change, while the working rules continue in the main platform texts.

The WHATWG HTML Living Standard’s Custom Elements chapter is the current place to read those rules. It defines registries, name checks, upgrades and reaction queues. The chapter also covers later situations such as adoption and form participation. The core story is enough to explain the new division of labor: the browser recognizes and activates registered element definitions; authors write the component’s useful work and decide which attribute changes matter.

Shadow DOM answers a different design question about a component’s internal tree and how outside content reaches it. Custom Elements answers who gives a tag a definition and how its life is managed. A component may use both mechanisms, but the badge and the room are separate inventions. In one, the browser runs the employment office. In the other, it keeps the building plans. Web pages became much easier to compose when authors could hand a tag a job and trust the browser to tell it when to show up.