Html5-h custom element


@Niaccurshi To be clear, this is a prollyfill - see these references: Extensible Web Manifesto, Building Polyfills - we’re looking to grow proposals outside of implementations, tighten the feedback loop and build semantics the way we build up language (see my post on this topic). Historically, an editor of the W3C HTML spec (like @SteveF_) might have an idea, he writes up a proposal and discusses it on the mailing list. Another editor might disagree about this or that. Hopefully the working group can resolve it. But then there’s WHATWG doing the same thing and the two might not agree. Then it comes to implementors who all have to agree, and tests and process and so on - all kinds of incentives and disincentives can slow this down. It can take years to come up with something only to find out that it doesn’t get used how we wanted because developers don’t find that intuitive. In this model, we can propose the future, coin some slang and good slang can be considered for native adoption - the process will be much smoother and faster because we have real data and experience to base it on.


It’s a custom element, custom elements must have a dash ‘-’ in their name (see How should I name my element?). If it became a standard html element it would likely become <h>.


Some developers do (will do a grep of webdevdata for examples). For years the W3C HTML spec promoted it alongside h1-h6 use, until I made some changes in the spec to align it with reality. (AFAIK the whatwg spec still does). There have been lots of articles about the miracle of the document outline and how it allows use of h1 only.

The truth be that any heading element (h1-h6) can be used in conjunction with sectioning elements and they will produce the same document outline (if the outline algorithm is implemented) but many people don’t grok that. So for back and forward compat using h1-h6 in conjunction with sectioning elements is the most robust pattern.


Thanks Brian, you are much more articulate on the subject than I :-).


Do you see <h> addressing any of the needs considered by <subhead>? (pardon the prefix dropping)


hi Jon, not really, I think subhead is a parallel discussion/experiment


@jonathantneal feel free to start a subhead thread on specifiction.


It seems a shame to me that we’re having to create a polyfill (or other methods) for something that’s in the spec already and should just be implemented by the vendors. I wish I understood more about why there was opposition to dealing with code structure more logically.

Given document outlines actually have a place in the spec (as opposed to, for example, the work done on responsive images) it feels like any polyfill should use the algorithm and responsible elements as defined, in the same way that people have been polyfilling HTML5 elements like video for backwards compatibility…ensuring people can code to HTML5 standards and then polyfill back from that.

I’m not against this solution in principle, I would like to make that clear(!), I’m just genuinely perplexed as to it’s lack of relation to standard elements as detailed above.

Also, as a note for clarity in where my part of this discussion is coming from, I am definitely one of those developers who uses <h1> throughout the document within appropriate sectioning elements. Since reading Steve’s views on where the document outline spec implementation was at, back whenever that was, I started with server side solutions to insert ARIA levels appropriately. This polyfill would be very useful for maintaining those levels in any dynamic pages I’d create. I’ve also generally taken to using [aria-role="X"] to do any level based styling (though page designs are usually too complex to rely on styling based on heading levels alone, if at all)


The discussion on [this bug][1] may be helpful in understanding why the acc implementation has not occurred and why i started work on html5-h. In the general sense there has been discussion about speccing/implementing the outline algo in browsers, but no implementer or even specifier interest.

I see it as a way to get the algo working while at the same time exploring the possibility of standardizing a <h> element along the way. Because to me a h1 will always be a h1, its semantics are written into its name.

[1]:[quote=“Niaccurshi, post:28, topic:438”] [aria-role=“X”] [/quote]

hope not as aria-role is not an attribute :slight_smile:


Oof, there’s the late night catching up with me, aria-level obviously!

Thanks for the earlier link, I guess that my views/discussion on the particulars of the valid context for the semantic scope of h1 would be better placed in there than on here? :wink: Needless to say I think I disagree on the use of h1 being inappropriate, but in the context of this polyfill is a moot point since the same additions need to be made to elements to provide the correct outlines for accessibility in either case.


Oh sorry, I missed that,

But it can be <h->, the - would even conceptually represent the missing number.

Just kidding…


Thanks everyone for your contributions! I think I get the specificity issue now; thanks – it’s a tough one without access to the browsers at a lower level, I fear. This is a reply specifically to @Jesse_Donat

The <hn> elements do impart meaning, and in a HTML4 setting, where they’re the only semantic “structuring” elements we have, they’re vital. However, if you’re already using HTML5 sectioning elements, then the document structure is already imparting that meaning, so we see using <hn> elements in HTML5 as a violation of DRY. Also, what if content is dynamically brought in from another source to form part of a larger page – the heading structure may need fixing in order for it to fit in the master document’s outline. If we have a universal heading element, it will fit in with the structure of the document in which it finds itself.

As accessibility folk, we often see incorrect document outlines – e.g. where heading levels have been missed, or headings are using in a way that doesn’t match the visual appearance of the page (sometimes people use the heading levels simply as a way to ease writing the CSS, not as a means to impart the relative importance of sections).

<html5-h> is an attempt to bring a universal heading element (such as that proposed for XHTML2 or that found in DocBook) to HTML, in recognition of the document structure defining the semantics.

I hope this explains our rationale, even if you feel that heading structure should take higher precedence than document structure.


@Niaccurshi thanks for your input - I too am concerned about introducing anything new/reinventing the wheel, but as @SteveF mentioned, we feel that this seems perhaps the “least worst” way for now. We do have two goals that are sometimes at odds with each other.

  1. Provide a universal heading that works now.
  2. Spec out and implement a reference universal heading element that is as close as possible to a native HTML element as we can get, in the hopes that its potential utility causes it to get adopted (or the outline algorithm to be implemented).

Web Components are very exciting as it seems they give us the ability to do 2 above, even if 1 could be achieved with a lower overhead (you maybe interested in this simple polyfill mentioned in a bug report on <html5-h>–I’ll be investigating its accessibility and element-ish properties in detail as soon as I am able; I suspect it still experiences the CSS specificity barrier).


Thanks for the further explanation @matatk, The problem for me is there is a 3rd goal that needs to be considered, and that is that sites still need to provide adequate information for SEO purposes. Unfortunately the use of anything other than h1-h6 will not provide this information, which goes back to my point to @SteveF that while I agree in principle with the use of a <h> element in the future, for polyfill purposes it seems to not be relevant as to whether you put a is="html5-h" property or similar on it.

IMO, if you use this polyfill is should just work on headers, whether <html5-h> or <hn>, as that’ll help more practical adoption of the technique of dynamic heading level ordering. No? If people don’t want to provide proper, spec driven, heading levels then they can do what they need to manually (or don’t want to do it at all), surely?


The point of is=“html5-h” is that you can put it on existing <h1> elements <h1 is=“html5-h”>, and use them instead of h2-h6 and they will expose the correct semantics when used in conjunction with sectioning elements.


Hi Steve, I’m maybe not making myself clear.

  1. if someone uses this polyfill, why would they not want the script to properly level that headers, with or without the "is"property?

  2. I assume the script would still work with h2-h6 (with or, preferably, without the “is” property) since they may be legitimately used for current standards seo while still wanting to leverage the power of the document outline through use of the polyfill.

For the best prospect of take up I’d hope this script worked on h1-h6 without needing additional properties. It’d certainly limit my ability to use it otherwise :slight_smile:


I believe you meant to say: Then the same instance above will be blue, not red…

I see your point regarding specificity, but I’m not sure this is a real issue. In my opinion, common cases is to avoid qualifying selectors and to start with generic styling.

So I’d expect to see something along these lines in a base style sheet:

[level="1"] {...}
[level="2"] {...}
[level="3"] {...}
[level="4"] {...}
[level="5"] {...}
[level="6"] {...}

with the use of classes in non generic style sheets, coming after “base”:

.special-hn {...}
.very-special-hn {...}


I have a few questions:

  • How will user agents react to a content author adding in specific levels inside a sectioned document, will flow continue from what they have specified or otherwise?
  • Is the is="html5-h" intending to be part of the eventual standard?
  • I don’t really get the use case for it much, especially as you mention it isn’t for SEO purposes for the polyfill.
  • I think I would suggest for the polyfill h1-h8 where h[n] closely matches what a preprocessor/javascript would output. SEO impact would be minimal, publishers can continue to use h1-h8 and drop in the script, when enough user agents support <h> elements then the switch should be fairly painless if CSS has been used correctly.
  • Are you likely to consider static rendering of level by the server instead as another offering/solution before user agents are adopting? For example Jekyll renders content once at publish time; that could be a good place to render the level attributes without client side JavaScript.
  • From an SEO perspective this could drop down to h1 - h8 until adoption also as well as using data-level (CSS could account for both html-h and h1-8 presence)
  • How will DOM manipulation impact the levels, if I moved a section element to be inside another section element, does that recalculate all the headings in the section I have moved?
  • If heavy effects were used how would this impact performance?

Some styling guidelines would help for content designer approval and I think suggesting a preprocessor for styling levels might be appropriate:

 @for $i from 1 through 8
    font-size: 5rem / $i

Which would output:

  html-h[level=1] {
    font-size: 5rem;

  html-h[level=2] {
    font-size: 2.5rem;


Along with similar examples demonstrating using colour filters like lighter and darker with similar fraction based calculations. Also examples of section style heading numbering would be brilliant too.

Do aural stylesheets get used by screen readers at all? If so I would suggest further examples here too.


I would rather go with <x-h> as the provisional name for what is hoped to become a standard <h>. <html5-whatever> sounds more like something I would use in a polyfill for a standardized-but-not-yet-implemented element, like <html5-picture>.


I’ve filed an issue with the W3C related to this topic. See