# All about HTML Custom Elements
Custom Elements is a [WHATWG] HTML [specification][spec] that
provides a mechanism for defining new behaviors (such as dynamic
content or interactivity) for HTML elements with custom names.
Custom elements are just HTML elements, with all of the methods and
properties of other, built-in elements. The only real constraint
is that
**[custom element names must contain a hyphen (`-`)](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name)**.
```html
Hi!
Custom elements can contain content!
And other custom elements!
```
**Note:** The adopted [custom element spec][spec], formerly known
as "v1", differs almost entirely from the original ["v0" spec][v0 spec].
If you've been using `document.registerElement()` from the v0 API,
then read on to see what's changed.
## Table of Contents
1. [Why custom elements?](#why-custom-elements)
1. [How do they work?](#how-do-they-work)
1. [Browser support](#browser-support)
1. [Customized built-in elements](#customized-built-in-elements)
1. [Observed attributes](#observed-attributes)
1. [Polyfills](#polyfills)
1. [Further Reading](#further-reading)
## Why Custom Elements?
* **Encapsulation.** Custom element names avoid ambiguity in
markup (versus, say, a `
` or `` with a "special"
class), and provide a solid foundation for scoped styles.
* If you've ever felt like it was wrong to define reuseable
components with "special" class names initialized by jQuery
selections that can only be called after the DOM is ready (or
rely on mutation observers to watch for new instances), then
custom elements could be your new jam.
* In native implementations (see [browser support](#browser-support)),
you can target custom elements before (`:unresolved` in the
[v0 spec]) and after (`:defined` in the [v1 spec][spec]) they've
been registered via JavaScript.
* **The DOM _is_ the API.** Components built with tools like jQuery
can be cumbersome to build, modify, and maintain because they often
introduce another layer of abstraction (such as the `jQuery` object
and its API) on top of the DOM. And while there's nothing to stop
one from building custom elements that use jQuery, D3, React, or
whatever under the hood, I've found custom elements made with
vanilla JS to be easier to grok and read.
Put another way: **The DOM isn't going away any time soon**, and
custom elements provide a solid conceptual _and_ technical
foundation on which all sorts of amazing things can be built.
* **Web Standards.** Custom elements are an adopted [WHATWG] HTML
[specification][spec]. That means that—in theory, at least—they
will _eventually_ be implemented natively in all modern browsers
with the same API.
Keep in mind is that **custom elements are not mutually exclusive
of other web component technologies**. In fact, I see them as a
powerful force multiplier of any technology that leverages them:
When designed well, custom elements put their power into the hands
of anyone who can write HTML. Great React components, for instance,
can be made even greater by packaging them up as custom elements.
## How do they work?
Custom element behaviors are added at runtime (whenever the
"registration" occurs in JavaScript), and can hook into a number of
different element _lifecycle events_:
1. **When an instance of the custom element is created**, either via
the class constructor or `document.createElement()`; or when
existing custom elements are registered.
1. **When an instance is "connected"** to the document,
either directly or indirectly. This may be called multiple times,
and is generally the best place to add event handlers.
1. **When an instance is removed** (or "disconnected") from the
document, either directly or indirectly. This may also be called
multiple times.
1. **When an attribute is changed**. You can also subscribe to specific
[observed attributes](#observed-attributes) if you only care about
attributes unique to your element, or to implement [attribute reflection].
## Browser Support
As of summer 2018:
* [Chrome has implemented][chrome] both the [v0 spec] and the adopted ["v1" spec][spec].
* [Safari has implemented][safari] so-called "autonomous" custom elements, but has
declined to support extension of built-in elements.
* [Firefox has implemented][firefox] the spec behind a feature flag.
Regardless of your support targets, you should use a [polyfill](#polyfills).
⚠️ When using custom elements—or anything involving JavaScript,
for that matter—**always design experiences for progressive enhancement**,
and plan for the possibility that JavaScript isn't enabled or available.
## The API
The custom elements API consists mainly of a [CustomElementRegistry] object
that can be used to register class constructors for custom elements by name:
```js
window.customElements.define('element-name', ElementClass);
```
Where `ElementClass` is a class that extends [HTMLElement]:
```js
// ES2015
class ElementClass extends HTMLElement {
constructor() {
super() // <-- this is required!
this.created()
}
created() {
console.log('hi!', this)
}
}
```
Custom element classes may implement any of the following lifecycle
(instance) methods:
1. `connectedCallback()` is called whenever the element is added to
the document, either directly (`document.body.appendChild(el)`) or indirectly
(as part of a fragment or a DOM tree that's added to the document).
1. `disconnectedCallback()` is called whenever the element is removed from
the document.
1. `attributeChangedCallback(attr, oldValue, newValue)` is called when
an _observed_ attribute (see below) is changed.
and the following static (class) properties:
1. `observedAttributes` is an optional array of attribute names for
which the `attributeChangedCallback()` will be called. If you do not
provide this property, the callback will fire for all attributes.
```js
// ES5
class CounterElement extends HTMLElement {
static get observedAttributes() { return ['value'] }
attributeChangedCallback(name, old, value) {
// we can safely ignore name here because 'value' is the only
// observed attribute
this.value = value
}
get value() {
return ('_value' in this)
? this._value
: (this._value = 0)
}
set value(value) {
this._value = value
}
}
```
## Customized built-in elements
⚠️ **Warning:** Safari does not _yet_ implement [this portion of the
spec][customized built-ins]. If you wish to use it, you will need a [polyfill](#polyfills).
Custom elements may extend built-in HTML elements with special
semantics or behaviors (such as `