Starlight Upgrade Raises CSS Specificity and May Restyle Docs Sites
Starlight 0.43.0, released Nov. 13, drops its forced :where() style scoping for Astro's attribute strategy, which can change how custom styles apply.

Starlight 0.43.0, a release of the Astro docs framework dated Nov. 13 in its release notes, stops forcing a single way of scoping component styles. Sites now get Astro’s default "attribute" strategy unless they set another one. The release notes mark the change as breaking and say it can alter which styles win on a page.
The new default raises specificity
Starlight previously “forced the "where" strategy,” the release notes say, producing selectors like :where(.astro-HASH). A :where() selector adds no specificity, so a site’s own CSS could override Starlight’s scoped rules with a plain class. Under the "attribute" strategy, the release notes say, “Attribute selectors have a higher specificity than :where() selectors.” The notes ask developers to check that their styles still apply and that the order in which rules win has not changed.
The change came in pull request #4190, which “Adds support for any Astro scopedStyleStrategy configuration.” Any value set in astro.config.mjs now applies to Starlight as well.
Components that pass a class to a child need a fix
The release notes single out sites and component libraries that hand a class from a parent component down to a child. Astro’s attribute strategy does not carry the parent’s scope along on its own, so the child must spread the parent’s data attribute onto the element that takes the class. The notes point to Astro’s styling guide for the pattern.
Sites that want the old behavior can set scopedStyleStrategy: "where" in the Astro config, according to the release notes.
Theme select drops a global API
A second potentially breaking change, pull request #4219, refactors the theme select menu “to reduce its JavaScript use.” The release notes say the global StarlightThemeProvider.updatePickers() API is gone. Projects and themes that override ThemeSelect should compare their version with Starlight’s updated ThemeProvider.astro, ThemeSelect.astro and LanguageSelect.astro.
The release also moves Starlight to i18next v27. The notes say, “We don’t expect any changes to impact Starlight users,” and point anyone calling the translation APIs directly to i18next’s migration guide.
Pagefind gets two indexing options
Starlight now passes Pagefind’s excludeSelectors and includeCharacters settings through “to customize how search indexes are built,” per pull request #3674.
A patch fix makes an aside throw an error when given an icon name such as constructor or toString. Version 0.43.1, also dated Nov. 13, fixes a regression that drew the <Aside> icon smaller than the icons in Markdown asides.
Key takeaways
- Starlight now follows
scopedStyleStrategyand defaults to"attribute". - Attribute selectors outrank the old
:where()selectors, so custom CSS can lose. - Set
scopedStyleStrategy: "where"to keep the old behavior. StarlightThemeProvider.updatePickers()has been removed.
The take
We think the style change is the one to test before upgrading, because it fails quietly. A build will pass and every page will render, yet a custom color or margin can stop applying. That happens because CSS picks the more specific rule, and Starlight’s scoped rules now outrank a plain class override. Either fix is cheap. Teams can upgrade a branch and compare a few pages with heavy custom styling against production, or add scopedStyleStrategy: "where" first and move to the new default later. Teams with their own ThemeSelect override should also search the codebase for updatePickers before they bump the version.


