Why is the content model for `<button>` limited to phrasing content?

[mfreed7]

The spec for <button> says:

Content model:Phrasing content, but there must be no interactive content descendant and no descendant with the tabindex attribute specified.

This issue is to ask: why the phrasing content limitation? (The interactive content limitation makes total sense.) I've asked around with some a11y folks, and as far as I've heard, this is unrelated to accessibility. It may be historical, from a time before CSS could be used change inline/block/etc. There would seem to be some very valid use cases for using a non-phrasing element like a <div> inside a button, such as for layout reasons.

I searched for other related issues, and could only find this one in WHATWG, and these two (888, 1332) on the validator. None gave particularly satisfying rationale.

This content model rule, AFAIK, is just a validator issue, since all browsers properly and interoperably parse and render <button><div></div></button>. And changing it would be a relaxation of the validator, which would seem to be backwards compatible.

Any reason not to relax the content model for <button>?

@scottaohara @sideshowbarker @aleventhal @una

[sideshowbarker]

I don’t know why the decision to limit button to phrasing content was originally made, but I can’t think of any reason not to relax it. So if we end up having agreement on that, and the change is made to the spec, then I’ll happily update the validator to conform to the spec change.

[domenic]

This appears to have been there from the beginning: https://searchfox.org/whatwg-html/diff/fe5d39724d647c0ab3d7bb11f9149800c9edd7bd/source#24064 .

I wasn't able to find any prior discussion by searching lists.whatwg.org or w3.org's bugzilla. I did find something similar for <summary>: https://www.w3.org/Bugs/Public/show_bug.cgi?id=24372 . It looks like the result there was allowing headings inside summary, not anything more general.

Could we hear a bit more about the use case? Presumably using a <div> is not actually important, since <span class="display: block"> works just as well.

[domenic]

In particular it's not clear what we would open this up to. For example, allowing headings inside buttons seems wrong. Similar for a variety of other elements like <noscript>, <map>, <dialog>. Sectioning content maybe? But probably not?

So this leads me to suspect the answer is "because phrasing content is the most natural existing category of things that make sense inside a button". If there are use cases for more specific categories, like we saw with headings inside <summary>, then probably we would expand on a case-by-case basis, still starting with phrasing content as the base.

[annevk]

"Layout" is not a valid reason. That makes it seem like a limitation of CSS, not HTML.

[sideshowbarker]

Maybe someone could run an HTTP Archive query to see how much real-world deployed content there is which has flow content in button.

I could also add a use counter to the HTML checker, but all that would end up giving us is just a raw percentage of documents that have been run through the checker that have flow content in button.

[sideshowbarker]

The core question asked in validator/validator#1332 is: Why is flow content now allowed in button but is allowed in a? Maybe there’s an obvious answer to that which I’m just not aware of. But I can understand why a developer might see that difference between the content models for button and a as an inconsistency.

To put it in other terms, one imaginable general articulation of the use cases for allowing flow content in button is: For similar reasons to those allowing flow content in a.

I have no strong opinion on it either way, except to say the HTML checker’s core purpose is helping developers statically catch unintentional markup mistakes — for example, catch cases where, say, they misplaced a </button> end tag and so they ended up with content that was meant to follow the button being instead unintentionally part of the button.

Another purpose of the HTML checker it to not cause developers to end up ignoring the checker — or stop using it completely — because they get annoyed and frustrated when they’re intentionally using markup in some (currently) non-conforming way (as long as it doesn’t have adverse effect on accessibility or have other problems among those listed in https://html.spec.whatwg.org/multipage/introduction.html#restrictions-on-content-models-and-on-attribute-values), and so the checker is reporting something to them as an error that they don’t perceive as a valid error.

In general there’s always a tradeoff between the purpose of being to try and help developers catch markup mistakes and the purpose of the checker behavior not being overly prescriptive to the point that it causes developers to get frustrated and annoyed to the degree that they stop using the checker.

But I don’t personally know enough about the use cases and deployed content to understand whether the no-flow-content-in-button restriction might be something a lot of developers in practice see as an overly prescriptive case.

[annevk]

We changed <a> model so you could make a clickable box (e.g., containing a heading, an image, and a description), which is a somewhat common UI pattern or at least used to be. Making such content a button feels like a stretch, but maybe? I'd love to see some actual examples.

[scottaohara]

if the crux of this issue is "can we just allow divs inside buttons", then sure, go nuts. people do it all the time and while it used to cause some issues for some screen readers, it mostly seems ok these days. But also, as Domenic mentioned, span is a thing too, so, maybe that's fine enough to expect developers to know when to use a div vs span?

But, if the goal is to expand beyond that - allowing more content types as descendants of buttons, then we venture into the current problematic territories of summary (i won't retread that conversation here) but also a. Hyperlinks being allowed to contain more than phrasing content has it's own problems - here's just one blog post that touches on why. It can be useful in some situations, and it can be absolutely bonkers broken UX in others... for instance if one were to wrap an entire table in a hyperlink... that's gross - having the accessible name of that link be a flattened text string of the entirety of all the tabular data. And if you think "oh well, put an aria-label on that link" then cool, now the browser has sent a signal to the AT of "ignore everything in this hyperlink - someone gave it an aria-label which means the content isn't important". So, horrible UX for AT, but valid HTML. Let's make sure to not let buttons do that too, please.

[patrickhlauke]

also depends then on how things are exposed in the accessibility tree (and whether or not things can be exposed in a sensible way when that happens). such as headings, or any other structural elements, being completely stripped of their actual semantics by virtue of being wrapped in a button, just because there's no sensible way (within the constraints of the platform's accessibility APIs) to have it any other way

[mfreed7]

Thanks for all of the comments and history here. This issue was opened because I had a conversation with someone who asked why they couldn't put a <div> inside the button. Perhaps a baby-step in this direction is to just expand to "phrasing content or a <div>"? I do see the points about other semantic element types being at least odd if not problematic. E.g. <button><h1>. But perhaps a non-semantic element like <div> which people tend to just reach for as the default structural block element would not cause problems?

I tend to agree with this comment - having rules in the validator that error out when there's no "good" reason to have a limitation leads to people ignore the validator. Additionally, it's actively helpful to developers to guide them away from things that are actually bad (e.g. <button><h1>) and let them do things that don't appear to cause harm (<button><div>).

[domenic]

Can you ask this person why a span does not work for them? For better or for worse, we have both, and have decided they have different use cases. If we want to try to erase the distinction between them and all div wherever span is allowed, we could consider doing so, but I don't think that we should do it as a one-off for button.

[mfreed7]

Can you ask this person why a span does not work for them? For better or for worse, we have both, and have decided they have different use cases. If we want to try to erase the distinction between them and all div wherever span is allowed, we could consider doing so, but I don't think that we should do it as a one-off for button.

Clearly a <span> can be made to work in any case that a <div> is used here. It's just that developers know to reach for <div> when they want a generic block-level element, except when inside a button. That's just another exception to the rule which is confusing and takes mental bandwidth. It's like English's "i before e" rule - there are so many exceptions that you can't use the rule. Since it seems like there's no actual reason for the <div> limitation, other than history, perhaps we can relax it?

I'd argue the same for other elements that restrict to phrasing content for no "good" reason.

[sbaechler]

Relaxing this rule would also be helpful from an accessibility perspective. Interactive elements that contain block elements cannot use the element directly. This often forces developers to use a very cumbersome workaround like this to make the element accessible:

<div
    tabindex="0" role="button" onclick="onClick()"
    onkeydown="handleKeyDown(event)"
>
    Button without button
</div>

<script>
function onClick() {
  console.log("Clicked!");
}

function handleKeyDown(event) {
    if (event.key === "Enter" || event.key === " ") {
        onClick();
    }
}
</script>

The idea with HTML 5 was to make HTML semantic. Limiting child elements based on layout properties is going against this idea.