Skip to content

Add :heading and :heading() pseudo-classes#11413

Merged
zcorpan merged 4 commits intomainfrom
zcorpan/heading-pseudo
Aug 11, 2025
Merged

Add :heading and :heading() pseudo-classes#11413
zcorpan merged 4 commits intomainfrom
zcorpan/heading-pseudo

Conversation

@zcorpan
Copy link
Copy Markdown
Member

@zcorpan zcorpan commented Jun 27, 2025

Fixes #11412.

(See WHATWG Working Mode: Changes for more details.)


/rendering.html ( diff )
/semantics-other.html ( diff )

Copy link
Copy Markdown
Member

@annevk annevk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

Should we revisit the UA style sheet at this point as well? Coupling them makes some sense to me.

@annevk annevk added addition/proposal New features or enhancements topic: selectors labels Jun 27, 2025
@annevk
Copy link
Copy Markdown
Member

annevk commented Jun 27, 2025

I guess leaving out the change to the individual hN selectors makes sense. We can make that change to the UA style sheet as part of the new attributes, as until then it wouldn't really be an improvement.

I'm double checking whether WebKit is interested, but I suspect so.

<code>h1</code>, <code>h2</code>, <code>h3</code>, <code>h4</code>, <code>h5</code>, and
<code>h6</code> elements.</p></dd>

<dt><dfn selector noexport data-x="selector-heading-functional">:heading(<var>An+B</var>#)</dfn></dt>
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider linking these to https://www.w3.org/TR/css-syntax-3/#anb-microsyntax and maybe https://www.w3.org/TR/css-values-3/#mult-comma as these are both parts of CSS syntax that aren't otherwise mentioned in the HTML spec as far as I can tell.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added references to these specs. Is that good enough?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I was thinking was the style the CSS specs use, where the parts of the syntax would be links to the spec section describing them. (Eg, the # would link to directly to the section saying what # does.)

But it looks like HTML doesn't link directly to CSS specs? If that's the case I think this should be fine, but I'm not an expert.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That could be done, but not inside a dfn since they are interactive. The code is also turned into a link, so can't use links inside.

HTML doesn't define the syntax, that is defined in https://drafts.csswg.org/selectors-5/#headings so I think it's OK.

@annevk
Copy link
Copy Markdown
Member

annevk commented Jun 27, 2025

@fantasai pointed out to me that in w3c/csswg-drafts#10296 (comment) there was discussion about a different specificity for these pseudo-classes, but this does not appear to be reflected in the changes to the Selectors specification, despite claims back in April that it would be. Can someone clarify this for me?

@keithamus
Copy link
Copy Markdown
Member

keithamus commented Jun 27, 2025

[...] specificity for these pseudo-classes [...]

The spec states: https://drafts.csswg.org/selectors-5/#headings

The specificity of :heading() is that of a class.

This was updated in w3c/csswg-drafts#12404 which while not updated in April as claimed, was updated today!

AIUI this is per the resolution in w3c/csswg-drafts#10296 (comment).

RESOLVED: :heading() has the expected class-level specificity

Copy link
Copy Markdown
Member

@annevk annevk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can consider WebKit supportive of adding these. @LeaVerou since you commented on the CSS issue regarding specificity, any final thoughts from you?

Comment on lines +76048 to +76049
<code>h5</code>, and <code>h6</code> elements that have a <span>heading level</span> among
<var>An+B</var>. <ref>CSSSYNTAX</ref> <ref>CSSVALUES</ref></p></dd>
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This last part is quite vague, but I guess it's good enough?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's the same language as in https://drafts.csswg.org/selectors-5/#headings

@LeaVerou
Copy link
Copy Markdown
Member

LeaVerou commented Aug 5, 2025

You can consider WebKit supportive of adding these. @LeaVerou since you commented on the CSS issue regarding specificity, any final thoughts from you?

I still don't have a strong opinion, I can see arguments for both class-level specificity and tag-level specificity.
Some reservations around ARIA heading roles not affecting this, especially since it means there is no way for web components to hook into it.
Also, just to make sure, presumably <h1 aria-level="2"> would match :heading(2) and not :heading(1), right?

@keithamus
Copy link
Copy Markdown
Member

keithamus commented Aug 5, 2025

Aria would always supersede. Consequently :heading(1), [role=heading][aria-level=1] would match the equivalent levels.

<h1 aria-level=2> would match :heading(1). Aria mustn’t influence CSS in that way. One can use the attribute selector mentioned above and ensure a good cascade order to circumvent any potential issues.

I wrote more about this over in w3c/csswg-drafts#12412 (comment) which hopefully details some of why it is untenable for :heading to match. Perhaps that's also a more fruitful place for discussion than this PR?

@annevk
Copy link
Copy Markdown
Member

annevk commented Aug 6, 2025

Indeed, long ago we have settled on ARIA not influencing semantics. It's an expert tool that solely influences AT. (This does mean that :heading(1) could match the same thing as [aria-level=2], but this would also be highly indicative of an authoring error.)

@LeaVerou
Copy link
Copy Markdown
Member

LeaVerou commented Aug 6, 2025

(This does mean that :heading(1) could match the same thing as [aria-level=2], but this would also be highly indicative of an authoring error.)

Re:authoring error, I think there are valid use cases for overriding heading level via aria-level. Polyfilling headingoffset for one :) Back in the days of the old HTML5 outline algorithm, I've been meaning to write a polyfill for it that worked by adding aria-level attributes, and just never got around to it.

@annevk
Copy link
Copy Markdown
Member

annevk commented Aug 6, 2025

That's why I wrote highly indicative and not that it's set in stone. 😊

@zcorpan
Copy link
Copy Markdown
Member Author

zcorpan commented Aug 7, 2025

I think I'd prefer the polyfill use case to use attribute selectors for aria-level over setting a precedent of making ARIA affect matching of pseudo-classes.

@zcorpan zcorpan merged commit 65dc095 into main Aug 11, 2025
2 checks passed
@zcorpan zcorpan deleted the zcorpan/heading-pseudo branch August 11, 2025 23:30
zcorpan added a commit to web-platform-tests/wpt that referenced this pull request Aug 11, 2025
foolip pushed a commit to web-platform-tests/wpt that referenced this pull request Aug 13, 2025
lando-worker bot pushed a commit to mozilla-firefox/firefox that referenced this pull request Aug 19, 2025
…, a=testonly

Automatic update from web-platform-tests
[selectors] Test :heading and :heading()

See w3c/csswg-drafts#11836 and whatwg/html#11413
--

wpt-commits: 7ed8a2090bf6b7b601fd03aa29eb3100721df4fa
wpt-pr: 53440
CSharperMantle pushed a commit to CSharperMantle/mozilla-firefox-dev that referenced this pull request Aug 26, 2025
…, a=testonly

Automatic update from web-platform-tests
[selectors] Test :heading and :heading()

See w3c/csswg-drafts#11836 and whatwg/html#11413
--

wpt-commits: 7ed8a2090bf6b7b601fd03aa29eb3100721df4fa
wpt-pr: 53440
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

addition/proposal New features or enhancements topic: selectors

Development

Successfully merging this pull request may close these issues.

Specify :heading and :heading() selectors

5 participants