HTML for Subheadings and Headings

Let’s say you have a double heading situation going on. A little one on top of a big one. It comes up, I dunno, a billion times a day, I’d say. What HTML do you go for? Dare I say, it depends? But have you considered all the options? And how those options play out semantically and accessibility-y?

As we do around here sometimes, let’s take a stroll through the options.

The visual examples

Let’s assume these are not the <h1> on the page. Not that things would be dramatically different if one of them was, but just to set the stage. I find this tends to come up in subsections or cards the most.

Here’s an example a friend brought up in a conversation the other day:

Here’s one that I worked on also just the other day:

And here’s a classic card:

Option 1: The ol’ <h3> then <h2>

The smaller one is on the top, and the bigger one is below, and obviously <h3> is always smaller than an <h2> right?

<h3>Subheading</h3>
<h2>Heading</h2>

This is probably pretty common thinking and my least favorite approach.

I’d rather see class names in use so that the styling is isolated to those classes.

<h3 class="card-subhead">Subheading</h3>
<h2 class="card-head">Heading</h2>

Don’t make semantic choices, particularly those that affect accessibility, based on this purely visual treatment.

The bigger weirdness is using two heading elements at all. Using two headings for a single bit of content doesn’t feel right. The combination feels like: “Hey here’s a major new section, and then here’s another subheading because there will be more of them in this subsection so this one is just for this first subsection.” But then there are no other subsections and no other subheadings. Even if that isn’t weird, the order is weird with the subsection heading coming first.

If you’re going to use two different heading elements, it seems to me the smaller heading is almost more likely to make more sense as the <h2>, which leads us to…

Option 2: Small ‘n’ mighty <h2> and <h3>

If we’ve got classes in place, and the subheading works contextually as the more dominant heading, then we can do this:

<h2 class="card-subheading">Subheading</h2>
<h3 class="card-heading">Heading</h3>

Just because that <h2> is visually smaller doesn’t mean it still can’t be the dominant heading in the document outline. If you look at the example from CodePen above, the title “Context Switching” feels like it works better as a heading than the following sentence does. I think using the <h2> on that smaller heading works fine there, and keeps the structure more “normal” (I suppose) with the <h2> coming first.

Still, using two headings for one section still feels weird.

Option 3: One heading, one div

Perhaps only one of the two needs to be a heading? That feels generally more correct to me. I’ve definitely done this before:

<div class="card-subheading">Subheading</div>
<h3 class="card-heading">Heading</h3>

That feels OK, except for the weirdness that the subhead might have relevant content and people could potentially miss that if they navigated to the head via screenreader and read from there forward. I guess you could swap the visual order…

<hgroup> <!-- hgroup is deprecated, just defiantly using it anyway -->

  <h3 class="card-heading">Heading</h3>
  <div class="card-subheading">Subheading</div>

</hgroup>

hgroup {
  display: flex;
  flex-direction: column;
}
hgroup .card-subheading {
  /* Visually, put on top, without affecting source order */
  order: -1;
}

But I think messing with visual order like that is generally a no-no, as in, awkward for sighted screenreader users. So don’t tell anybody I showed you that.

Option 4: Keep it all in one heading

Since we’re only showing a heading for one bit of content anyway, it seems right to only use a single heading.

<h2>
  <strong>Subheading</strong>
  Heading
</h2>

Using the <strong> element in there gives us a hook in the CSS to do the same type of styling. For example…

h2 strong {
  display: block;
  font-size: 75%;
  opacity: 0.75;
}

The trick here is that the headings then need to work/read together as one. So, either they read together naturally, or you could use a colon : or something.

<h2>
  <strong>New Podcast:</strong>
  Struggling with Basic HTML
</h2>

ARIA Role

It turns out that there is an ARIA role dedicated to subtitles:

👉If you want to semantically identify a heading subtitle, look no further than role="doc-subtitle" https://t.co/wG2rVfU3d4#HTML #ARIA #WebDev pic.twitter.com/uaHcVRp6oz

— Steve Faulkner [email protected] (@stevefaulkner) March 7, 2020

So like:

<h2 class="card-heading">Heading</h2>
<div role="doc-subtitle">Subheading</div>

I like styles based on ARIA roles in general (because it demands their proper use), so the styling could be done directly with it:

[role="doc-subtitle"] { }

Testing from Steve and Léonie suggest that browsers generally treat it as a “heading without a level.” JAWS is the exception, which treats it like an <h2>. That seems OK… maybe? Steve even thinks putting the subheading first is OK.

The bad and the ugly

What’s happening here is the subheading is providing general context to the heading — kinda like labelling it:

<label for="card-heading-1">Subheading</label>
<h2 id="card-heading-1" class="card-heading">Heading</h2>

But we’re not dealing in form elements here, so that’s not recommended. Another way to make it a single heading would be to use a pseudo-element to place the subhead, like:

<h2 class="card-heading" data-subheading="Subheading">Heading</h2>

.card-head::before {
  content: attr(data-subheading);
  display: block;
  font-size: 75%;
  opacity: 0.75;
}

It used to be that screen readers ignored pseudo-content, but it’s gotten better, though still not perfect. That makes this only slightly more usable, but the text is still un-selectable and not on-page-findable, so I’d rather not go here.