Use CSS for table of contents highlighting

[delucis]

What version of starlight are you using?

0.37.4

What is your idea?

CSS is slowly getting towards having the capabilities necessary to power current item highlighting like we use in our table of contents (currently implemented with an IntersectionObserver).

The :target-current pseudo-class combined with the scroll-target-group property (both Chromium-only at time of writing) can be used to achieve highlighting like we do currently.

See “Creating a scroll-spy with 2 lines of CSS” by Una Kravets for one implementation example that matches our use case.

Why is this feature necessary?

The CSS implementation is significantly simpler than our fairly complex IntersectionObserver logic, so would improve maintenance once browser support is sufficient. I haven’t tested, but I’d also expect it to be a performance improvement as we would be able to offload the logic to the browser, which can run it optimally under the hood rather than our main thread JS, which notably needs to do stuff like element measurement, which can force layout if we’re unlucky.

This may also be a good candidate for progressive candidate even before widespread browser support is available: we could use a @supports query to test for the availability of the necessary CSS features and only fall back to the JS version in browsers where it isn’t available.

That said, we probably can’t do that immediately. The relevant spec is still an editor’s draft, so it may potentially change. Also, there are no signals from other browser engines at time of writing (Gecko, Webkit).

Migration path

One thing to bear in mind for a migration like this will be the change in styling hooks which could impact themes/user customisations. Currently, we add aria-current="true" to the highlighted link item (styled using [aria-current="true"]). This change would instead use :target-current as the styling hook. If we took a progressive enhancement approach, we’d need to be using both selectors until switching to only :target-current is possible.

Accessibility considerations

I’m curious about the accessibility impact. It’s not yet clear to me if browsers will expose something similar to aria-current in the accessibility tree for links matching the :target-current selector. There’s some discussion of the accessibility of these new APIs in the W3CTAG repo, but I don’t see this specific aspect mentioned there. The demo linked above does not show something equivalent in the accessibility tree in Chrome 144. I also haven’t evaluated how important or valuable our use of aria-current is for users in this context.

Do you have examples of this feature in other projects?

No response

Participation

• I am willing to submit a pull request for this feature.