Config to enable/disable theming

[lorenzolewis]

What version of starlight are you using?

0.5.6

What is your idea?

A way to set the Starlight site to only be dark or light (or auto) via the config

Why is this feature necessary?

Sometimes branding only has light or dark mode colors (or a developer only wants a specific theme). This would expose an option in the Starlight config for a user to only create a dark or light website. This could disable the theme dropdown in the navbar as well as reduce the resulting CSS.

A use case from Discord: https://discord.com/channels/830184174198718474/1070481941863878697/1125991126885744723

Do you have examples of this feature in other projects?

Docusaurus theme config for color: https://docusaurus.io/docs/api/themes/configuration#color-mode---dark-mode

I like how they also let the developer set a "preferred" mode (defaultMode) so that the dev could specify a specific theme but then the user could also override it if they'd like. I remember some conversations over there around all the different permutations and states this could result in so it would probably be good to have a solid think through what the API and UX would be around this.

Participation

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

[delucis]

I’m pretty strongly in favour of letting site users pick dark/light mode — forcing someone to use colours different from their preference is an accessibility concern.

If people want it enough, I think we could make the default theme configurable though — i.e. disrespectUserThemePreference: 'light' 😛 — so that pages load in light/dark instead of auto while still letting users switch to their preference. There are situations where this could make sense, like https://terrateam.io/ where the transition from their dark marketing homepage to the docs in light mode (when that’s the device preference) can be quite jarring.

[lorenzolewis]

Love that suggested key name ;)

Get what you're saying around accessibility (and even my personal experience with being blinded by the light[-theme]).

Maybe a config option could be: preferredTheme: 'userPreference' | 'dark' | 'light';

[delucis]

Yeah! I might suggest defaultTheme or initialTheme perhaps? And the values would probably be clearest if they match how we label them in the UI 'auto' | 'dark' | 'light'. We could make it clear in docs that setting this config option overrides user preference.

[schalkneethling]

Being able to set the initial theme would be enough for me. Thanks, @delucis

[dhruvkb]

Personally, I would prefer sites have 'auto' theme be the default, as it allows me to set my light/dark preference once (at the device level) and have my web browsing experience consistently match my preference.

[delucis]

Personally, I would prefer sites have 'auto' theme be the default

Yeah, absolutely, we won’t change that default.

[magicDGS]

I also would like to be able to disable the light/dark mode switch to control better the branding of my documentation. In my case, I would like to have a dark-only mode for the website hosting the documentation and even if I style in the same way the light/dark mode, the switch will appear making the site look like if the light mode is not working.

I agree that the default should still be keeping the switch and default to auto, but having a one-style is an use-case that I can see as valuable in case that somebody needs it.

[binaryCrossEntropy]

Hey Ya!
I was wondering if this feature will be released. I've built my site and I need 'dark mode' to be the only option.

[bramsmulders]

Our Astro site doesn't have a dark mode, and we'd like to document it in starlight. But the theme toggle prevents us from deploying the documentation to a public site. Not all design systems/brandings have taken dark/light mode into account(yet) and forcing this in starlight is not productive it think. I agree it should be enabled by default, but a configuration option would be very nice.

[delucis]

This can be worked around using component overrides currently. There are two theme-related components:

• ThemeProvider — adds a <script> and <template> to set-up theme support, could be overridden to just contain

  <script is:inline>
  document.documentElement.dataset.theme = 'light'
  </script>

  (is:inline prevents Astro bundling the script, which would make it run too late)

• ThemeSelect — adds the actual theme picker UI. This could be overridden with an empty component to hide it.

Hope that helps!

[bramsmulders]

@delucis Awesome! This worked very well, thanks for your swift reply!

[TechClusterHQ]

@delucis The workaround worked great, but the divider is still in the titlebar, with nothing next to it (I also got rid of the social links in the astro.config.mjs). Can I override that too? I wasn't able to find the component.

[delucis]

Ah yeah, I guess you can hide that with a little bit of custom CSS:

.social-icons::after {
  display: none;
}

[dealmengor]

Hi, is possible to know when this feature will be ready?

[davidfiala]

Just to make it super clear on how to follow the instructions above to force exactly dark or only light mode without any user choice:

• Create two new components.
  1. An empty one. This will be used to hide the drop-down selector for dark/light/auto. It doesn't hide it: It actually replaces the dropdown with empty content.
  2. Another that forces the theme via JS. It also doubles as a global custom CSS to hide some extra space after the social icons.
• Modify the astro.component.mjs in order to recognize those two new components as overrides.

mkdir -p src/components
touch src/components/EmptyComponent.astro src/components/ForceDarkTheme.astro

Set file contents of EmptyComponent.astro (yes, it's 3 dashes, and then another 3 dashes)

---

---

Set files contents of ForceDarkTheme.astro

---

---

<script is:inline>
  document.documentElement.dataset.theme = 'dark';
</script>
<style is:global>
  .social-icons::after {
    display: none;
  }
</style>

Update your astro.component.mjs to include the ThemeProvider and ThemeSelect overrides:

// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      // ...
      components: {
        ThemeProvider: './src/components/ForceDarkTheme.astro',
        ThemeSelect: './src/components/EmptyComponent.astro',
      },
      // ...
    }),
  ],
  // ...
});

---

On a personal note, I think it's a fair request to ask for a way to enforce that only one theme is available (choosen by the designer/developer). People never use a product in the way that the original developers intended.

As people force hacks like the above, I fear (without knowing) that bundle sizes, css sizes, etc won't be optimized because they won't know to cut out the unused theme.

Worse, in some future version of astro/starlight, this hack may just break.

Accessibility is important. But likewise, sometimes a design or resources simply calls for only a certain color scheme to exist. It is, IMHO, worse for a user to be broken/unreadable/confused because they picked light mode on their device when the developers only implemented a dark screen option- they have no indication why the site is even broken or unreadable.