Glossary

Audience
Mixed

• Autonomous Custom Element
• Customized Built-in Element
• Custom Element Registry
• Disabled
• FOUC
• Inert
• Interactive State
• Persistent State
• Upgrade

Autonomous Custom Element

This is likely what folks are referring to when they say "custom element". Autonomous custom elements implement behavior "from scratch".

This type of custom element is similar to:

• React Components
• VueJS Components
• Angular 1.x Element Directives

Example

<my-stuff></my-stuff>
<x-foobar></x-foobar>

Customized Built-in Element

These elements extend functionality of native elements, like <button>.

NOTE: There is currently no support for these types of custom elements in ANY browser.

Example

<button is="fancy-button">Fancy Button</button>

Custom Element Registry

For an element to be upgraded, the browser needs to know how it should be styled and behave. This is done with the custom element registry, by providing the name of the custom element along with its behavior definition.

class MyElement extends HTMLElement {
  /* ... */
}

customElements.define('my-element', MyElement);

Disabled

Similar to inert elements, disabled elements prevent interactive states. However, disabled elements also prevent background functionality.

FOUC

"Flash of Unstyled Content" - Before custom elements are upgraded, they have very basic styles applied to them (typically styled as inline elements with no frills). After upgrade, an element's style is fully defined and all should be well. Before upgrading, the browser displays a flash of unstyled content.

Inert

Inert elements prevent interactive states (i.e., can't be focused, clicked, etc.), but background functionality may still continue to run (e.g., listening for events, polling an API for data, etc.).

Inert elements are commonly associated with modal dialogs, because elements in the background should be made inert, per WAI-ARIA guidelines.

Interactive State

NOTE: Interactive states may be applied in addition to persistent states.

Interactive states require user interaction and are styled using pseudo classes.

State	Selector	Events
Blurred	n/a	blur
Focused	:focus	focus
Hovered	:hover	mouseover, etc.
Pressed	:active	mousedown, keydown, touchstart, etc.

Persistent State

Persistent states exist without user interaction. These states typically are configured through HTML attributes. Sometimes it makes sense to apply an associated JavaScript property to the element, as well.

State	Attribute	Property
Default	n/a	n/a
Disabled	<hx-foo disabled>	elFoo.disabled = {Boolean}
Indeterminate	<hx-foo indeterminate>	elFoo.indeterminate = {Boolean}
Invalid	<hx-foo invalid>	elFoo.invalid = {Boolean}
Selected	<hx-foo checked>	elFoo.checked = {Boolean}

Upgrade

Browsers treat any unknown tags as a generic "unknown" element. Once the custom element registry is made aware that the element is a custom element, it will be upgraded to its custom behavior and appearance.