18

I've gone through the code for The Incredible Accesible Dialog v3 and i have noticed that they are using an <h1> tag

<div id="modal" aria-hidden="false" aria-labelledby="modalTitle" aria-describedby="modalDescription" role="dialog">
    <div id="modalDescription" class="screen-reader-offscreen">...</div>
    <h1 id="modalTitle">...</h1>
    <p>...</p>
    <form name="form1" onsubmit="return false;">...</form>
</div>

So that got me thinking, is that actually semantically correct? I mean everyone keeps saying there should only be 1 <h1> in a document.

Note that in previous versions of the dialog, they gave the dialog a role="document" which makes using <h1> ok imho

Improve this question

2 Answers 2

Reset to default
29

I know you have accepted an answer, but it is not quite right.

Sure, you can put an <h1> in a dialog and nothing will catch fire. It will technically not be correct, however.

The heading level should represent where it lives in the page structure. If your page has a single <h1>, which is your best way to go, then the dialog should get a heading level that corresponds to where it lives within the structure of the page (its content).

Most likely the dialog does not fit into the flow of the rest of the content, so it would appropriately be a sub of the page's <h1> (since it is a dialog about the page), making the dialog take <h2>.

If you are using a tabbed interface, and you have built your tabs to each be <h2>s, and your dialog applies to a specific tab, then your dialog would take an <h3>.

And so on.

Adding role=document does not change this (and may be a mis-application of the document ARIA role unless you are explicitly testing with assistive technology to ensure it works as you expect).

You can see that the all-<h1> model is now considered an anti-pattern in HTML 5.1. The W3C HTML validator will now flag it.

You can read more about the approach to structure headings in an article penned by one of the editors of the HTML5 spec: Computer says NO to HTML5 document outline

So, to answer your original question, no it is not semantically correct to use <h1> in a dialog.

Improve this answer
5
  • While I do agree with you, the interesting thing is that in the spec there is no mention of this "rule". I checked before even posting this question. And yes the dialog I was looking at (The Incredible Accesible Dialog) is in fact tested with a number of screen readers (listed at the bottom), so they would not use ARIA roles lightly.
    – Dogoku
    Commented Jul 20, 2016 at 2:11
  • 3
    1. The spec does mention the <h1> "rule" and has had a warning since HTML5.0 along with open bugs to fix it. 2. See the blog post about the dialog: "removed the role=”document” from the contents of the window. This was originally inserted to deal with the way NVDA interacted with role=”dialog”, but that issue has since been resolved in NVDA."
    – aardrian
    Commented Jul 20, 2016 at 2:52
  • 1
    As of October 2020, the first example in "§ 4.3.3 The section element" states: "Notice how the use of section means that the author can use h1 elements throughout, without having to worry about whether a particular section is at the top level, the second level, the third level, and so on." See: html.spec.whatwg.org/multipage/…
    – gfullam
    Commented Oct 22, 2020 at 21:26
  • 2
    Which is incredibly frustrating considering it also lists <hgroup> (which has no support) and leans on the Document Outline Algorithm which has never been implemented. So if you are supporting users, ignore that part of the spec. If you are targeting code compliance, go nuts. Ref: adrianroselli.com/2016/08/…, codepen.io/stevef/post/a-decade-of-heading-backwards
    – aardrian
    Commented Oct 29, 2020 at 20:40
  • 1
    This again depends on the context of the dialog – dialog does however not appear to be a sectioning content or section root element, which is inconsistent and a bit odd given it can be useful to give dialogs a heading. I can not find any WHATWG mention of it being "sectioning root" anymore, but it used to say this in w3 specifications: w3.org/TR/2018/WD-html53-20180809/… Not sure if this means we should avoid using headings entirely in dialogs, and perhaps use something else, like a more neutral p or div however.
    – Jacob
    Commented Aug 9, 2023 at 9:07
3

Semantically, you can start any new section of the document (section, article, nav, aside, header, footer) with an h1.

It will change with HTML 5.1, but h1 might still be used in dialog (*) elements because they are considered as "sectioning roots". See http://w3.org/TR/html51/sections.html#headings-and-sections).

Certain elements are said to be sectioning roots, including blockquote and td elements. These elements can have their own outlines, but the sections and headings inside these elements do not contribute to the outlines of their ancestors.

blockquote body details dialog fieldset figure td

Because of the lack of support by browsers and accessibility technologies, although it's "semantically" correct, this does not mean that it's a good design choice. Authors should prefer preserving the h1..h6 hierarchy across sections to have a coherent, hierarchized/nested document outline (h1>h2>h3>...h6) which will be provided to assistive technologies.

(*) Note that, as pointed by another user, it will then be necessary to use a dialog rather than a role=dialog element to have full support.

Improve this answer
8
  • 5
    This is no longer true (and has never worked as originally proposed): html5doctor.com/computer-says-no-to-html5-document-outline
    – aardrian
    Commented Jul 19, 2016 at 20:27
  • 3
    I disagree that it is semantically valid. Semantically, you are saying the dialog is a peer to the page as a whole, when it is not. It is defined within the context of the page. This is not new in HTML 5.1, this reflects how the <h#> elements were designed from day one.
    – aardrian
    Commented Jul 19, 2016 at 23:18
  • 3
    Except, a) OP is not using the <dialog> element, b) having its own outline still does not matter since no browser supports the outline algorithm and it has been noted in HTML5 and HTML5.1 that it should be avoided and c) the W3C link you offer even says "Authors should use headings of the appropriate rank for the section’s nesting level."
    – aardrian
    Commented Jul 20, 2016 at 12:03
  • a) No, role=dialog is not equivalent to <dialog>. Adding a role never makes it equivalent, whether for the browser or assistive technology, it just exposes some of its aspects (which is why you still have to script keyboard support for role=button). b) Semantics are different from structure. <h#> imparts both, <strong> imparts only semantics. Technology support is important for AT, so yeah, we are talking about that. c) You are unclear. Regardless, it is still not semantically correct.
    – aardrian
    Commented Jul 20, 2016 at 13:47
  • Thank you for your comments, and helping me improving my answer.
    – Adam
    Commented Jul 20, 2016 at 14:05

Not the answer you're looking for? Browse other questions tagged or ask your own question.