Skip to content

[Starlight] Auto-set theme from param #26412

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: production
Choose a base branch
from
+15 −0
Open

[Starlight] Auto-set theme from param #26412

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions astro.config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,7 @@ export default defineConfig({
Sidebar: "./src/components/overrides/Sidebar.astro",
PageTitle: "./src/components/overrides/PageTitle.astro",
TableOfContents: "./src/components/overrides/TableOfContents.astro",
ThemeProvider: "./src/components/overrides/ThemeProvider.astro",
},
sidebar,
customCss,
Expand Down
14 changes: 14 additions & 0 deletions src/components/overrides/ThemeProvider.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
import Default from "@astrojs/starlight/components/ThemeProvider.astro";
---

<script is:inline>
const params = new URL(location.href).searchParams;
const theme = params.get("preferred-color-scheme");
if (theme === "dark" || theme === "light") {
document.documentElement.dataset.theme = theme;
Copy link
Collaborator Author

@kodster28 kodster28 Nov 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

This line doesn't appear to do anything based on testing. Keeping it for the moment, but probably superceded by the local storage setting line in 10.

Ideally, I'd prefer to keep this behavior (9 over 10) -- and just load this time in this theme -- instead of setting the local variable to avoid someone getting docs theming set unexpectedly

localStorage.setItem("starlight-theme", theme);
}
</script>

<Default><slot /></Default>
Copy link
Collaborator

@colbywhite colbywhite Nov 10, 2025

Choose a reason for hiding this comment

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

How does this play with Starlight's version? Which one gets loaded first?

You might want to not use the Default and combine the existing logic to give you something along the lines of

const urlTheme = new URL(location.href).searchParams.get("preferred-color-scheme");
const storedTheme =
			typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
const theme =
			urlTheme || storedTheme ||
			(window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark');
// do the same logic as Starlight's from here on out

I'm guessing the standard way to override Starlight comps won't allow that? And thus we need to replace it instead of adding to it?

Copy link
Collaborator

@colbywhite colbywhite Nov 10, 2025

Choose a reason for hiding this comment

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

Also, I think the following use case could happen:

  • The URL is theme=light, which loads the light theme.
  • User clicks the doc's theme picker and chooses the dark theme.
  • Now the URL has light but the doc is dark.

Not sure we care about that though. It in theory could break copy/pasting of links depending on how Astro handle relative links when there's a query param. (I assume it ignores it.) If this case matters, then something in ThemeSelect likely needs to be overridden as well.

Copy link
Collaborator Author

@kodster28 kodster28 Nov 11, 2025

Choose a reason for hiding this comment

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

How does this play with Starlight's version? Which one gets loaded first?

You might want to not use the Default and combine the existing logic to give you something along the lines of

const urlTheme = new URL(location.href).searchParams.get("preferred-color-scheme");
const storedTheme =
			typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
const theme =
			urlTheme || storedTheme ||
			(window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark');
// do the same logic as Starlight's from here on out

I'm guessing the standard way to override Starlight comps won't allow that? And thus we need to replace it instead of adding to it?

I think so, as far as I understand Starlight's overrides.

You can append logic to the component via the Default pattern, but once you start touching the internals you have to rewrite a lot.