The hgroup element

by .

Update 16th April, 2013. hgroup has now been removed from the HTML5 specification. We are working on an article to help guide authors on which markup patterns they should use instead.

Update 4th April, 2013. Please note that following this decision, hgroup will be removed from the HTML5 specification. As such, we don’t endorse using it on production sites.

One of the new elements defined in HTML5 is <hgroup>, used for grouping titles with their associated subtitles. But why do we need <hgroup> when we’ve already got the <header> element? In this article, we’ll do our best to answer that question.

What is the <hgroup> element?

Here’s what the spec says about <hgroup>:

The hgroup element is typically used to group a set of one or more h1-h6 elements — to group, for example, a section title and an accompanying subtitle.

So what does that mean?

<hgroup> acts as a wrapper for two one or more related heading elements possibly contained within a <header> element. It can only contain a group of <h1><h6> element(s), and it should be used for subtitles, alternative titles, and tag lines.

The easiest way to demonstrate proper use of <hgroup> is through some examples. Thanks to Dr. Oli for letting us use his examples.

An article with one title

The title consists of a single <h1>, so neither <hgroup> nor <header> is required:

<article>
  <h1>Title goes here</h1>
  <p>Lorem Ipsum dolor set amet</p>
</article>

An article with a title and metadata

Here we’re using <header> to group the title and associated metadata, so an <hgroup> is not required:

<article>
  <header>
    <h1>Title goes here</h1>
    <p><time datetime="2010-03-20">20th March, 2010</time></p>
  </header>
  <p>Lorem Ipsum dolor set amet</p>
</article>

An article with a title and subtitle

An <hgroup> contains the title and subtitle of the article:

<article>
  <hgroup>
    <h1>Title goes here</h1>
    <h2>Subtitle of article</h2>
  </hgroup>
  <p>Lorem Ipsum dolor set amet</p>
</article>

An article with a title, subtitle and metadata

An <hgroup> contains the title and subtitle of the article, and then a <header> contains the metadata and the <hgroup>:

<article>
  <header>
    <hgroup>
      <h1>Title goes here</h1>
      <h2>Subtitle of article</h2>
    </hgroup>
    <p><time datetime="2010-03-20">20th March, 2010</time></p>
  </header>                
  <p>Lorem Ipsum dolor set amet</p>
</article>

Real world examples

On Alex Gibson’s MiniApps, he uses <hgroup> to include a tag line after the main “MiniApps” heading. (This is also what we’ve done on this site if you view the source.)

Screenshot from http://miniapps.co.uk
Screenshot from Alex Gibson’s MiniApps site

So why use <hgroup>?

It’s all about the document outline. When grouping headings in an <hgroup> element, the outline algorithm will mask the lowest level all but the highest level heading in the group from the resulting document outline. Using MiniApps as an example again, in his markup (although this is simplified), Alex uses:

<header>
  <hgroup>
    <h1><a href="/">Mini Apps</a></h1>
    <h2>Web applications for iPhone, Android & other mobile platforms</h2>
  </hgroup>
</header>

The <hgroup> contains both <h1> and <h2> elements, but the outliner only includes the <h1>. This is illustrated in the image below. (Please ignore the “untitled section” as well. This is caused by the nav element, and a change request has been submitted to address this.)

The page outline from http://miniapps.co.uk
Document outline of miniapps.co.uk

We’ll be covering document outlines in another article, so I won’t go into detail here. You can test your own pages in the HTML5 Outliner to ensure that you’re using the heading elements within <hgroup> correctly.

Summary

In this article, we’ve demonstrated how to use the <hgroup> element effectively. To recap:

  • If you have a simple title with a single heading element (<h1><h6>), you do not need an <hgroup>.
  • If you have a title with subtitle(s) or tag lines (i.e., more than one consecutive <h1><h6>), group them in an <hgroup>.
  • If you have a title with subtitle(s) and other metadata associated with the section or article, place both the <hgroup> and the metadata within a single <header> element.

Let us know how you’re using <hgroup> in your HTML5 projects!

73 Responses on the article “The hgroup element”

Jacob Rask says

Is it required to have more than one hx element in an hgroup, or could I use it as a generic wrapper where titles sometimes will have subtitles but sometimes not (with dynamic content)?

jethro larson says

I’m still not impressed with hgroup. I can see how it *might* improve semantics, but it doesn’t seem like something that would get much use. Especially compared to other possibilities like <field> http://html5doctor.com/your-questions-5/

chip johnston says

it seems like adding a whole new element for 1 maybe 2 lines of code

Nick Edwards says

So, the hgroup element can only contain h1-h6 tags, nothing else?

That seems a bit odd. How often do websites use more than one header next to each other like that? Maybe once on a page?

Whats the big benefit of doing this anyway? Is there even one?

Natalia Ventre says

I don’t fully understand the application if the hgroup element in a website, because having more than 1 title is an exception. HTML as a markup language is used to format text for e-readers too, are this new semantic elements (section, article, header, hgroup, etc.) going in that direction?

Richard Clark says

@Jacob, you can use hgroup if you only have one heading yeah.

@Jethro, fair point, I think it’ll be used a fair bit for page headers (like on this site) but I’m not sure where else. If you think the field element is needed I suggest you submit it ot the WHATWG.

@Chip, yes but aren’t most new elements doing that? The idea is that all these new elements will add semantics and stop us using a generic div so often.

@Nick, yes that’s right see here hgroup markup W3C. Other part of question explained to Natalia as well.

@Natalia (& Nick) Having more than 1 heading may be an exception but the book example you quote is actually the perfect reason to have the element. Imagine a web app is automatically creating a contents page for chapters that have subheadings. These subheadings could then be automatically removed from the contents page because the lowest level heading would be masked by using hgroup.

Lastly, regarding e-books you might find this A list apart article from Joe Clark useful.

gossi says

Even though I might find this useful for the outline process, this is heavy work for us, just for that (article > header > hgroup…) 3 Opening tags, just for having an article with a headline ?!?

However, how does on follow with structuring its code between and is the next headline h2? Do I start a new with a new h1? Do I follow with h3 because of the h2 in the hgroup (well this one makes least sense to me, actually).

Thanks

Alohci says

I ran this :

<!DOCTYPE html>
<title>Test</title>
<hgroup>
<h1>This is an H1</h1>
<h2>This is an H2</h2>
<h3>This is an H3</h3>
</hgroup>
<p>My first para</p>

through gsnedders’s outliner tool (http://gsnedders.html5.org/outliner/). Only the H1 is listed.

You say

When grouping headings in an element, the outline algorithm will mask the lowest level heading in the group from the resulting document outline.

To me that implies that both the H1 and H2 should appear in the outline. Is the outliner wrong or have I what have I misunderstood?

Richard Clark says

@gossi, the examples in the article show you when you need to use a header & hgroup element and when you don’t. Some HTML from your second example got stripped but essentially you would use a h1 as your first level heading in each article. If that article has multiple sections you can also use a h1 in each section. Does that make sense?

@Alohci, no the outliner is correct it’s my mistake. The wording is incorrect and the outliner should only show the highest ranked heading. Good spot, thanks.

Anonymous says

IMO a tag/strap line should be marked up using the tag as it’s not a heading.

John Allsopp says

I still fail to see any use for the hgroup element other than to fix a problem with the outline algorithm in HML5.

Like the article/section distinction, anything that is extremely difficult to plain to experts in the field probably needs to be rethought from the ground up.

And since word processors, and the like have been doing very complex outlines/tables of contents only using heading levels for decades, what’s the need for the complex outlining approach in HTML5 that I suspect the vast majority of developers won’t adopt?

Jack Osborne says

@John Allsopp I’m in total agreement with you.

gossi says

@richard: Well, we are now given the opportunity to solve a problem with different methods and all are correct in some way. Hell, this makes html5 more difficult rather than easier :( It should turn the other direction right?
And how do we tell the knowledge to clients? Lets assume the following. We (developers) created a sth. where the user is able to post content (a blog post, a page in a cms, e.g.) and we give them a wysiwyg editor…

Joe says

I always felt H1, H2, etc were crap remnants from the age of HTML before CSS.

With the evolution of DIVs, IDs, and classes, I find it hard to find a purpose for heading tags in general.

HTML Outliner? Seems to be a tech-fix for poor UI, navigation, and structure of content.

Now I probably need to read a LOT more into this – but the concept seems a bit silly to me.

Joe says

After posting my comment – I can see HTML Outliner or whatever being useful for mobile and small devices – and of course separate mobile CSS files.

The biggest question I have with tech issues isn’t how cool, how fancy, or how well it works. My question is – what is the true purpose of this?

Richard Clark says

@JohnAlsopp, I’m completly with you on the complexity issues of hgroup/section & article. I can see a use for hgroup but I’m also pretty sure that there must be a better way around it. As you say word processing packages have been doing it for a while now.

@gossi, yes it’s slightly confusing but in general, if a heading has a subheading associated with it use a hgroup around them both.

@Joe, headings are very useful for creating outlines, tables of contents etc automatically. The outliner is handy to check the structure of your documents. The really reason behind it is a little more complex though, I’ll talk you through it briefly but we’ll have another article explaining it in more detail soon(ish).

The outline algorithm is handy because you can use multiple h1′s in your document. E.g each nested section can have a h1 within it. The outline algorithm will then automatically calculate that headings true level of importance based on how deep it’s nested.

For example if you have 3 nested sections each with a h1, the deepest level h1 is calculated by the outline algortihm to be a h3 on document A. Nothing too clever there and why not just use a h3? However, imagine that nested section was aggregated into another site which then sat in 4 nested sections. The outliner can then calculate that on that page the heading is equivalent to a h4 on document B.

I know this isn’t explained very well but hopefully it makes a bit of sense and like I say we’ll cover it in more detail in an article soon.

Have a read of this too from the WHATWG spec..

Joe says

Wow, thanks for the quick response! I do use heading quite often in my work, more so out of necessity. I’m trying to do more and more semantic HTML. Especially when using CMS.

I come from more of an art background, and this has led into UI design, PHP, etc. Sometimes I run into RoadBlocks where I see H1 tags (or the HGROUP in this case) and I have a really hard time wrapping my brain around it’s “purpose”.

Thanks for the feedback and the info! You know your stuff.

Callum says

I think I get the point of hgroup. I will try to explain my understanding of it (which might be wrong)…

Looking at the source of a Wikipedia article, it starts something like this:

<body>
<h1>Surfer Rosa</h1>
<h3>From Wikipedia, the free encyclopedia</h3>
<p>First paragraph of article...</p>

The h3 is used as a tagline. You might think they should use an h2, but maybe they were concerned that an h2 would imply that the following few intro paragraphs were a section titled “From Wikipedia, the free encyclopedia”. So they went straight for an h3, in an attempt to remove it from the document outline.

So, if I understand correctly, HTML5′s hgroup is intended to resolve this dilemma. You can optionally use an h[2-6] element for some other purpose (eg. a tagline) without affecting the document outline.

In HTML5, Wikipedia’s opening markup might be changed to something like this:

<body>
<header>
<hgroup>
<h1>Surfer Rosa</h1>
<h2>From Wikipedia, the free encyclopedia</h2>
<hgroup>
</header>
<p>First paragraph of article...</p>

That makes sense to me — it means the h2 will be ignored in the article outline, which is good. (One thing: why not use a p element for a tagline, instead of an h2? There’s probably a good reason, but I’m not sure what it is.)

Given that the HTML5 spec says that an hgroup will be interpreted for document outline purposes as the highest h[1-6] element inside it, does that mean that the following code would also be legal?

<body>
<header>
<hgroup>
<h2>Wikipedia presents</h2>
<h1>Surfer Rosa</h1>
<hgroup>
</header>
<p>First paragraph of article...</p>

I hope so, because I’ve wanted to use this sort of structure in the past. For example on websites listing concerts, the promoter often wants to write “[Promoter name] presents” before the title of the gig — basically a subheading, but one used before the main heading. Putting the above snippet through the outliner, it does seem to work as intended.

Rich Clark says

@Callum, that’s pretty much spot on, in your third example you’ll only see the ‘Surfer Rosa’ in the document outline. Also it’s important to remember that it doesn’t have to be a h1 that shows, just the highest level heading in the hgroup.

Thom says

I’m a bit confused how this usage might affect folks using assistive technology such as screen readers. If wrapping semantic headings within a group removes them contextually from the document outline, how does this aid to the semantic structure of a document. I’m probably burned out after a long day, but trying to wrap my head around the usefulness of such an element. Accessibility notwithstanding (and #a11y should never not withstand… ever), it seems like a good idea, but it runs the risk of promoting irresponsible (and unsemantic) coding.

And what is up with the return of the <b> to our collective consciousness… yuck!

Richard Clark says

@Thom, removing headings from the outline doesn’t mean that they won’t be read by a screenreader. Hgroup is helps user agents to create a table of contents for a document so will mask straplines etc. Think about a book or encyclopedia that has a lot of subtitles or subheadings.

As for <b> I suggest you read Oli’s article to see how the meaning has changed.

Scoobiscus Magazine says

Hi, thanks for the awesome post!
I would love to know why this :

<hgroup>
<h1> Logo </h1>
<p> Tag line </p>
<nav>
<ul>
<li>An Item</li>
<li>An Item</li>
<li>An Item</li>
<li>An Item</li>
</ul>
</nav>
</hgroup>

Can I put the a website logo, tagline, and main navigation inside the <hgroup> element in the <header> element ?

When I check this code in the W3C vaildator it says I can’t put the <nav> element in the <hgroup> element! for me it sounds more semantic and makes more sense if I could put the nav in the <hgroup> in the <header> !

I need more clarification on this point.

Thanks!

Richard Clark says

@scoobiscus – no you can only put h1-h6 elements inside a hgroup

fberriman » hgroups and sub-titles says

[...] on HTML5 Doctor, John Allsopp appears to find fault with this element also and suggests that the requirement for hgroup is symptomatic of a flaw in the outlining algorithm. I [...]

Brent Lagerman says

this comment might be better placed on another page of this site, but since I found the document outliner here I figured I’d just post here:

When I outline the HTML5doctor page I get a lot of entries that say ‘untitled section’

Aren’t these entries in the outline useless for someone using a screenreader or anyone for that matter? It seems like it would be better to use divs instead of those section elements so they don’t show up in the outline.

brent
@
mimoYmima.com

Patrick Samphire says

I must admit that I’m still not totally clear about when to use hgroup and header in conjunction.

For example, the following is pretty clearly correct and makes sense:

<header>
<hgroup>
<h1>Title</h1>
<h2>Subtitle</h2>
</hgroup>
<p>Text</p>
</header>

But how about this:

<header>
<hgroup>
<h1>Title</h1>
<h2>Subtitle</h2>
</hgroup>
</header>

Should the header element be included here, where only h1-h6 elements that are logically grouped in an hgroup are included? What semantic meaning do the header and hgroup offer in this case? It appears to be legitimate according to the spec, but pointless.

Even more so, the following:

<header>
<hgroup>
<h1>Title</h1>
</hgroup>
</header>

Again, apparently fits the spec, but in this case, the h1 could sit on its own, or sit inside a header element only, or sit inside an hgroup element only and still fit the spec.

I guess what I’m saying is that the spec seems clear in certain circumstances, but in others it’s really unclear as to what the most suitable usage is.

Richard Clark says

@Brent, the untitled sections are for elements such as nav, that create an implied heading in the outline but don’t require a heading in the markup. We have plans to write a detailed article on document outlines so be sure to look out for it.

@Phil, I recommend this article by Steve Faulkner on aria landmark roles.

@Patrick, good question. For your first example, as you say it makes perfect sense to use hgroup & header. For your second example, ditch header if it serves no purpose (if you need a style hook you can always use div if header doesn’t offer you the right semantics), hgroup doesn’t have to be in a header. Finally, in your last example, you’re spot on, I’d remove everything and just use the h1 – the outline will be created regardless of using a header or hgroup element.

Patrick Samphire says

Thanks, Richard. Basically, the principle would be ‘use as few as the elements as possible’ which makes good sense.

Ryan says

Is hgroup still part of the HTML5 spec? The last I read on the mailing list it was about to be removed.

Thanks.

Shawn says

Since hgroup is a block element, if you are going to wrap a title inside of a div anyway for styling, would it be wise to use the hgroup element as the wrapper rather than just a div even though it’s not required like the following:


<article>
<hgroup class="entry-title">
>h2<Post Title Here</h2>
</hgroup>
<p>Lorem ipsum dolor sit amet</p>
</article>

Lisa says

Thanks for the post (and actually, the site) and great that you reply to people’s questions. I’m just customising a wordpress for the first time in ages and came up against hgroup.

All that you’ve said makes perfect sense, I guess I still just don’t really see a desperate point for it… I get how to use it, but I need to look at the outliner in more detail I guess. The aggregated content sample was a good way of describing how the structure can fall back and be read in different contexts but still, how often does that happen? I’ll keep an eye on the Hokey Cokey post to see if it gets shaken out again!

Someone commented further up here, “why do we need header tags anyway” and I just wanted to throw in the dirty phrase no one has mentioned (because you’re all far more concerned with the craft, which I love, but I’ve got clients who are very concerned with it) – SEO. Also, we’ve written systems that read code and they look for header tags (actually, I suppose looking for titles and subtitles could be handy…hey, I’ve almost convinced myself!). So now I’m off to read about the outliner and am wondering how multiple h1 tags will go down with SEO types who haven’t read this/anything similar…

Thanks! Lisa x

CKuhn203 says

It seems to me that a lot of people are getting confused about the tag. The tags are heading tags. Not headers. You should only have one and one on a page. I think confusion about the starts to clear up once you understand this. the hgroup defines a Heading with a subtitile. That’s all. Simple.

CKuhn203 says

Any way… I forgot to escape. You should only have one header tag and one footer tag on a page. The hgroup defines a heading with a subheading. This adds some semantics to a style convention that a lot of authors like to use. Like I said, simple. What’s everyone so up in arms about?

Patrick Samphire says

You should only have one header tag and one footer tag on a page.

I’m not sure that I understand your comments, but it’s certainly not true that you can only have one header tag and one footer tag per page.

Brent Lagerman says

I guess I still just don’t really see a desperate point for it (hgroup)… I get how to use it, but I need to look at the outliner in more detail I guess.

It’s very useful once you understand how the outliner works. Lots of times you want to have a subheading for a header and the most logical markup for that would be another heading tag with a lower number, but you almost never want that to show up in your page outline so this hgroup tag give you the ability to bundle them both together and only the first one gets outlined…

b r e n t

Ckuhn203 says

@ Patrick
I’m not a professional web developer or programmer, but I have enough experience to know that just because you can do something doesn’t mean you should. All of the documentation I have seen implies that header and footer should be used as the header and footer of the page. In my opinion this is good practice as it clearly defines the different sections of your page. What exactly does it mean to have two headers on a site? Does this mean your logo, site title, and horizontal nav bar show up twice, or is there confusion about what these tags are for?

Brent Lagerman says

@CKuhn you’re thinking about the old way of writing HTML, HTML5 introduces sectioning elements to break up your document into different sections, articles, asides.. etc… Each of these can have it’s own header and footer and each should have it’s own heading structure starting with H1, so you do end up with a lot of header tags, footer tags and LOTS of H1s… At first this seems kinda insane I agree, but it is a good thing, it helps parts of your document be split out for syndication, it also give you the ability to mark up your document in a way that gives it a very useful outline which could be used by screen readers and helps google and other spiders understand what your document is about…

brent
@
mimoYmima.com

Patrick Samphire says

@Ckuhn203

You need to look more closely at the HTML5 specification. You can have multiple headers and footers, one of each for the page, and one of each for any of the sectioning elements on the page. You don’t have to have them, but they demarcate the header and footer parts of sectioning elements when they are needed.

John F. Mercer says

I’ve heard that the element is about to get tossed out of the spec. Is this true? Could anyone clarify this for me? Thanks.

Alice Wonder says

I’ve heard it is on the chopping block as well.
I currently use it but not within article semantics, I use it within document level header element (where role=”banner”) to have web site name followed by tag line.

Since it is outside the scope of main content, it’s semantic value really is not worth anything to me, and if I end up needing to switch back to div element to wrap those headings, it won’t make a lick of difference as far as I can tell to any html clients.

James Donaldson says

When I see the requirement that only that only <h1>…<h6> tags should appear inside an , is there an implicit qualification that that<a> and <img> are implicit qualifications to this if they appear inside <h1>…<h6> tags themselves?

vijaysany says

the thing i have doubt is when to use and when not to use the and . can any one place a good tutorial on this.

thanks

Thoufeeq says

so is useless if you are not using a tagline along with the title, or grouping the s.

Lukas says

<q cite="The contains both and elements”>

is there also h3-h6 headlines?

Mikes says

I am very likely never going to use the hgroup tag. Waste of my time. Pretty sure an indented h1 stands out well enough. And if I am already using headers then definitely see no point.

Kevin Oliveira says

Great article for those just starting to develop with HTML5, I was already using hgroup, but gave me a simple question and I had to search and your article is complete. Thank you! ;)

Jon says

Thank you so much. Just starting to use HTML5.
This will be helpful!

Peter K. Spies says

Support Your Local hgroup!
1st things 1st: I’m not trying to criticize your article, Richard. It’s a fine and very understandable one, in my opinion. Thank you!
What I should like to kill is the pest of using for subtitles and taglines.

Let’s talk language: What is a subtitle? Well, let’s see what it’s not. It’s not a full-grown title. It’s a title’s assistant. Hence the name. It can – all by itself – never be a method of summing up and/or announcing a text that follows. It cannot do the work alone. Any subtitle on it’s own cannot pilot the thing which it sits before.
You can take the (main) title and throw the subtitle out of the cockpit. And the passenger words of the following text will still feel perfectly safe.
But the other way ’round? No go.

And what is a tagline? It’s not any kind of title at all. Not even an assistant or an apprentice. It’s a boast. Or it’s a marketing device, disguised as real information, to make people smile.
It’s an animator in place of a stewardess, at best.

So what have these two got to do with : A headline of the second tier? Absolutely nothing!
(A subtitle could perhaps qualify as some kind of or 2 and a half, and so on. But a tagline …)

Therefore – in my humble opinion – , used thusly, is nothing but a hack. It works, because subtitles and taglines, tagged falsely , can hide from the eyes of an Outliner if they manage to huddle under the collective cloak of an . Wonderful. Thank you! We really needed this.

#1) Or is h short for hixie? (Cut that off, if you please …)
#2) [Sorry, I had to write this!:-]

Ben says

@Natalia (& Nick) Having more than 1 heading may be an exception but the book example you quote is actually the perfect reason to have the element. Imagine a web app is automatically creating a contents page for chapters that have subheadings. These subheadings could then be automatically removed from the contents page because the lowest level heading would be masked by using hgroup.</blockquote

Agree with this although that would also assume:

There are other "sub headings" at the same chapter, e.g siblings otherwise there is no point in the each chapter/group or the hgroup
- So a partial example to use a hgroup would be on a product listing page, where the linked to product page has:
- h1 = 1
- h2 = 4
- etc

- the hgroup would contain a reference to the first h2?

- Should this also then be encouraged to have an anchor link?

Jeff says

Concerning your update about hgroup being removed: so now, what to do to handle subtitles?

PS: this is really a stupid decision: something was working and useful (and even: necessary), and they decide to remove it!

Bertilo Wennergren says

I’ve defended “hgroup” before, but since it’s gone, I just removed all my uses of “hgroup” and put in “header” instead. Changing the stylesheets was a bit difficult, but it seems OK now.

Richard Clark says

@Jeff & @Bertilo – we’re working on an article to explain a little more about hgroups removal and how to mark up subtitles etc.

virgilio says

When working on my web page (http://working.virgiliodelavega.com/ and, using hgroup, the Validator gives me an error:

The hgroup element is obsolete. To mark up subheadings, consider either just putting the subheading into a p element after the h1-h6 element containing the main heading, or else putting the subheading directly within the h1-h6 element containing the main heading, but separated from the main heading by punctuation and/or within, for example, a span class=”subheading” element with differentiated styling. To group headings and subheadings, alternative titles, or taglines, consider using the header or div elements.

This is what I am using

Contact me
Drop me a line using contact form below. Thank you

Any idea or help? Thx

Brent Lagerman says

thanks steve, great reference, using a span in the h1 is what I needed – b

Rick says

I just got this error in the HTML validator:

Element hgroup not allowed as child of element div in this context.

Does this mean that the hgroup-element needs to be inside of an article?

Rick says

Oh … I see it’s kicked. Never mind folks!

Join the discussion.

Some HTML is ok

You can use these tags:
<a href="" title="">
<abbr title="">
<b>
<blockquote cite="">
<cite>
<del datetime="">
<em>
<i>
<q cite="">
<strong>

You can also use <code>, and remember to use &lt; and &gt; for brackets.