Are custom elements valid HTML5?

Question

The Custom Elements specification is available in Chrome and Opera, and becoming available in other browsers. It provides a means to register custom elements in a formal manner.

Custom elements are new types of DOM elements that can be defined by authors. Unlike decorators, which are stateless and ephemeral, custom elements can encapsulate state and provide script interfaces.

Custom elements is a part of a larger W3 specification called Web Components, along with Templates, HTML Imports, and Shadow DOM.

Web Components enable Web application authors to define widgets with a level of visual richness and interactivity not possible with CSS alone, and ease of composition and reuse not possible with script libraries today.

However, from this excellent walk through article on Google Developers about Custom Elements v1:

The name of a custom element must contain a dash (-). So <x-tags>, <my-element>, and <my-awesome-app> are all valid names, while <tabs> and <foo_bar> are not. This requirement is so the HTML parser can distinguish custom elements from regular elements. It also ensures forward compatibility when new tags are added to HTML.

Some Resources

• Example Web Components are available at https://WebComponents.org
• WebComponents.js serves as a polyfill for Web Components until they are supported everywhere. See also the WebComponents.js github page & web browser support table.

It's possible and allowed:

User agents must treat elements and attributes that they do not understand as semantically neutral; leaving them in the DOM (for DOM processors), and styling them according to CSS (for CSS processors), but not inferring any meaning from them.

http://www.w3.org/TR/html5/infrastructure.html#extensibility-0

But, if you intend to add interactivity, you'll need to make your document invalid (but still fully functional) to accomodate IE's 7 and 8.

See http://blog.svidgen.com/2012/10/building-custom-xhtml5-tags.html (my blog)

N.B. The answer below was correct when it was written in 2012. Since then, things have moved on a bit. The HTML spec now defines two types of custom elements - "autonomous custom elements" and "customized built-in elements". The former can go anywhere phrasing content is expected; which is most places inside body, but not e.g. children of ul or ol elements, or in table elements other than td, th or caption elements. The latter can go where-ever the element that they extend can go.

---

This is actually a consequence of the accumulation of the content model of the elements.

For example, the root element must be an html element.

The html element may only contain A head element followed by a body element.

The body element may only contain Flow content where flow content is defined as the elements: a, abbr, address, area (if it is a descendant of a map element), article, aside, audio, b, bdi, bdo, blockquote, br, button, canvas, cite, code, command, datalist, del, details, dfn, div dl, em, embed, fieldset, figure, footer, form, h1, h2, h3, h4, h5, h6, header, hgroup, hr, i, iframe, img, input, ins, kbd, keygen, label, map, mark, math, menu, meter, nav, noscript, object, ol, output, p, pre, progress, q, ruby, s, samp, script, section, select, small, span, strong, style (if the scoped attribute is present), sub, sup, svg, table, textarea, time, u, ul, var, video, wbr and Text

and so on.

At no point does the content model say "you can put any elements you like in this one", which would be necessary for custom elements/tags.

Basic Custom Elements and Attributes

Custom elements and attributes are valid in HTML, provided that:

• Element names are lowercase and begin with x-
• Attribute names are lowercase and begin with data-

For example, <x-foo data-bar="gaz"/> or <br data-bar="gaz"/>.

A common convention for elements is x-foo; x-vendor-feature is recommended.

This handles most cases, since it's arguably rare that a developer would need all the power that comes with registering their elements. The syntax is also adequately valid and stable. A more detailed explanation is below.

Advanced Custom Elements and Attributes

As of 2014, there's a new, much-improved way to register custom elements and attributes. It won't work in older browsers such as IE 9 or Chrome/Firefox 20. But it allows you to use the standard HTMLElement interface, prevent collisions, use non-x-* and non-data-* names, and define custom behavior and syntax for the browser to respect. It requires a bit of fancy JavaScript, as detailed in the links below.

HTML5 Rocks - Defining New Elements in HTML
WebComponents.org - Introduction to Custom Elements
W3C - Web Components: Custom Elements

Regarding The Validity of The Basic Syntax

Using data-* for custom attribute names has been perfectly valid for some time, and even works with older versions of HTML.

W3C - HTML5: Extensibility

As for custom (unregistered) element names, the W3C strongly recommends against them, and considers them non-conforming. But browsers are required to support them, and x-* identifiers won't conflict with future HTML specs and x-vendor-feature identifiers won't conflict with other developers. A custom DTD can be used to work around any picky browsers.

Here are some relevant excerpts from the official docs:

"Applicable specifications MAY define new document content (e.g. a foobar element) [...]. If the syntax and semantics of a given conforming HTML5 document is unchanged by the use of applicable specification(s), then that document remains a conforming HTML5 document."

"User agents must treat elements and attributes that they do not understand as semantically neutral; leaving them in the DOM (for DOM processors), and styling them according to CSS (for CSS processors), but not inferring any meaning from them."

"User agents are not free to handle non-conformant documents as they please; the processing model described in this specification applies to implementations regardless of the conformity of the input documents."

"The HTMLUnknownElement interface must be used for HTML elements that are not defined by this specification."

W3C - HTML5: Conforming Documents
WhatWG - HTML Standard: DOM Elements