Dark/Light theme toggle is not working at all in my Astro project #410

AoSankaku · 2025-12-17T18:20:13Z

AoSankaku
Dec 17, 2025

In my website (in development), the code block is still dark in light mode.

Tried solutions

Reading documentation: No sufficient information about theme toggle and usage of useDarkModeMediaQuery.
Toggling useDarkModeMediaQuery on and off: Absolutely not working.
Asking to AI: Complete waste of time. Nothing worked well.
Reading people's code on github and mimicking: Nothing worked at all.
Setting themeCssRoot: No effect.
Swapping dark and light theme order in themes array: Not worked.

expressiveCode({
themes: ['one-dark-pro', 'one-light'],
useDarkModeMediaQuery: false, // disable auto media query
themeCssRoot: 'html', // EC will attach variables to
})

Current problematic code

astro.config.mjs

// @ts-check
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import sitemap from '@astrojs/sitemap';
import icon from 'astro-icon';
import yaml from '@rollup/plugin-yaml'
import { DEFAULT_LOCALE_SETTING, LOCALES_SETTING } from './src/i18n/locales';
import { remarkTocTrigger } from './src/plugins/remark-toc-trigger.mjs';

import expressiveCode from 'astro-expressive-code';

// https://astro.build/config
export default defineConfig({

  // Sitemap
  site: 'https://aosankaku.net',

  // Integrations
  integrations: [react(), icon(), sitemap({
    /*
    i18n: {
      defaultLocale: 'ja',
      locales: {
        ja: 'ja-JP',
        en: 'en-US',
      }
    }
    */
  }), expressiveCode({
    themes: ['one-dark-pro', 'one-light'],
    useDarkModeMediaQuery: false,   // disable auto media query
  })],

  // i18n
  i18n: {
    defaultLocale: DEFAULT_LOCALE_SETTING,
    locales: Object.keys(LOCALES_SETTING),
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: false,
    },
  },

  // Path
  trailingSlash: 'always',

  markdown: {
    remarkPlugins: [remarkTocTrigger],
    gfm: true,
  },

  // Vite
  vite: {
    plugins: [yaml()],
    ssr: {
      noExternal: ['styled-components']
    },
    server: {
      watch: {
        ignored: ['**/node_modules/**', '**/.git/**'],
      }
    },
  },
});

Layout.astro

---
import {
  useTranslations,
  getLocalePaths,
  LOCALES,
  DEFAULT_LOCALE,
  type Lang,
} from "@/types/i18n";
import { SITE_TITLE, SITE_DESCRIPTION } from "@/consts";

const t = useTranslations(Astro.currentLocale as Lang);
const langs = Object.keys(LOCALES);
const defaultLocale = DEFAULT_LOCALE;
---

<!doctype html>
<html lang={DEFAULT_LOCALE}>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <link rel="sitemap" href="/sitemap-index.xml" />
    <meta name="generator" content={Astro.generator} />
    <slot name="head" slot="head" />
    <script is:inline>
      const getThemePreference = () => {
        // 1. Check for saved preference in localStorage
        if (
          typeof localStorage !== "undefined" &&
          localStorage.getItem("theme")
        ) {
          return localStorage.getItem("theme");
        }
        // 2. Fallback to system preference
        if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
          return "dark";
        }
        // 3. Default to 'light'
        return "light";
      };

      const theme = getThemePreference();

      // Apply the class before the browser renders the content
      if (theme === "dark") {
        document.documentElement.classList.add("dark");
      } else {
        document.documentElement.classList.remove("dark");
      }
    </script>
  </head>
  <body>
    <main id="main-content">
      <slot />
    </main>
  </body>
</html>

<style>
  html,
  body {
    margin: 0;
    width: 100%;
    height: 100%;
    background-color: var(--color-background);
    color: var(--color-text);
    max-width: 100vw;
    overflow-x: hidden;
    transition:
      background-color 0.5s ease,
      color 0.5s ease;
  }

  :global(a) {
    color: var(--color-primary);
  }

  :root,
  .dark {
    transition:
      --color-text 0.3s ease,
      --color-text-sub 0.3s ease,
      --color-background 0.3s ease,
      --color-primary 0.3s ease,
      --color-surface 0.3s ease,
      --color-card 0.3s ease,
      --color-blogcard 0.3s ease;
  }

  /* Light theme */
  :root {
    --color-text: #1a1a1a;
    --color-text-sub: rgba(26, 26, 26, 0.75);
    --color-background: #ffffff;
    --color-primary: #0056b3;
    --color-surface: #f4f4f4;
    --color-card: #bebebe;
    --color-blogcard: #ebebeb;
  }

  /* Dark theme */
  .dark {
    --color-text: #f0f0f0;
    --color-text-sub: rgba(240, 240, 240, 0.75);
    --color-background: #1a1a1a;
    --color-primary: #8ab4f8;
    --color-surface: #2c2c2c;
    --color-card: #696969;
    --color-blogcard: #3d3d3d;
  }
</style>

BlogArticleLayout.astro

---
import Layout from "./Layout.astro";
import Header from "@/components/Header.astro";
import Footer from "@/components/Footer.astro";
import { Image } from "astro:assets";
import ogDefaultImage from "@/assets/og-default.png";
import formatToJSTDate from "@/utils/formatToJSTDate";
import { Icon } from "astro-icon/components";
import type { MarkdownHeading } from "astro";

interface Props {
  frontmatter: any;
  headings: MarkdownHeading[];
}

const { frontmatter, headings } = Astro.props;
const { slug } = Astro.params;
const { thumbnail } = frontmatter;

// Thumbnail generation

const images = import.meta.glob<{ default: ImageMetadata }>(
  `../content/blog/**/*.{jpeg,jpg,png,gif}`,
  { eager: true },
);
const articleImage =
  images[
    `../content/blog/${slug}/${thumbnail ? thumbnail.replace(/^\.\//, "") : null}`
  ]?.default ?? ogDefaultImage;

const articleDate = formatToJSTDate(frontmatter.date);
const lastUpdate = frontmatter.lastUpdate
  ? formatToJSTDate(frontmatter.lastUpdate)
  : null;

// TOC generation

const toc = headings.filter((h) => h.depth > 1 && h.depth < 4);
---

<Layout>
  <Header />
  <div class="blog-hero">
    <Image src={articleImage} alt={frontmatter.alt} />
    <p class="category">{frontmatter.category}</p>
    <h1>{frontmatter.title}</h1>
    <div class="date-container">
      <Icon name="mdi:calendar" size="1.1em" /><p class="date">{articleDate}</p>
      {
        lastUpdate && (
          <>
            <Icon name="mdi:update" size="1.1em" />
            <p class="date">{lastUpdate}</p>
          </>
        )
      }
    </div>
  </div>
  <div class="container">
    <slot />
  </div>
  <Footer />
</Layout>

<style>
  h1 {
    text-align: center;
    margin: 18px 40px 26px 40px;
    word-break: auto-phrase;
    font-size: 36px;

    @media (max-width: 768px) {
      font-size: 24px;
      margin: 8px 40px 16px 40px;
    }
  }

  .container {
    max-width: 768px;
    padding: 0 30px 80px;
    margin: 0 auto;
    p {
      max-width: 100vw;

      a:first-child {
        word-break: break-all;
      }

      code {
        word-break: break-all;
      }
    }
    img {
      max-width: 100%;
      object-fit: contain;
      height: auto;
    }

    h2 {
      margin-top: 60px;
    }
  }

  .blog-hero {
    max-width: 1080px;
    margin: 0 auto 40px auto;
    text-align: center;

    img {
      max-width: 100%;
      object-fit: cover;
      aspect-ratio: 1280 / 720;
      height: auto;
    }

    .date {
      padding-right: 0.5em;
    }

    .date-container {
      font-size: 0.8em;
      color: var(--color-text-sub);
      padding: 0 12px;
      display: flex;
      align-items: center;
      justify-content: center;
      gap: 4px;
      height: 1.2em;
      color: var(--color-text-sub);
    }

    .category {
      background-color: var(--color-text-sub);
      color: var(--color-background);
      display: inline-block;
      text-align: center;
      padding: 0 14px;
      margin: 32px 0 0 0;
      border-radius: 8px;
      font-size: 0.9em;
    }
  }
</style>

<script is:inline define:vars={{ toc }}>
  const container = document.getElementById("article-toc-trigger");
  if (container && toc.length > 0) {
    const title = document.createElement("h2");
    title.innerText = "Table of Contents";

    const list = document.createElement("ul");
    toc.forEach((h) => {
      const li = document.createElement("li");
      li.style.marginLeft = `${(h.depth - 2) * 20}px`;
      const a = document.createElement("a");
      a.href = `#${h.slug}`;
      a.innerText = h.text;
      li.appendChild(a);
      list.appendChild(li);
    });

    container.appendChild(title);
    container.appendChild(list);
  }
</script>

Resources

Problematic website

You can see the code block is always black even you are in light mode. Reloading won't change anything.

https://aosankaku-website-2025.pages.dev/blog/gatsby-graphql-override/

Repository

https://github.com/AoSankaku/aosankaku-website-2025

Answered by AoSankaku

Dec 20, 2025

OK, after research (and with help by Gemini because my English is not so good), I managed to solve this with:

    themes: ['one-light', 'one-dark-pro'],
    useDarkModeMediaQuery: false,
    themeCssSelector: (theme, { styleVariants }) => {
      // 2. If the theme is 'one-dark-pro', trigger it when .dark class is on <html>
      if (theme.name === 'one-dark-pro') return '.dark';
      // Otherwise, it's the default theme (one-light)
      return false;
    },

And the crucial concepts are:

The first theme is the default theme. The order absolutely matters.
useDarkModeMediaQuery must be disabled in order not to let EC respond to @media query (This is the very first time to implement light…

View full answer

delucis · 2025-12-18T11:05:54Z

delucis
Dec 18, 2025
Maintainer

Hi @AoSankaku is this still an issue? I looked at https://aosankaku-website-2025.pages.dev/blog/gatsby-graphql-override/ and the theme seems to toggle as expected.

0 replies

AoSankaku · 2025-12-18T11:52:27Z

AoSankaku
Dec 18, 2025
Author

Thank you for your quick responce, today I implemented force temporary fix on AoSankaku/aosankaku-website-2025@e10bb42, which is redundant and inefficient.

The problematic deploy is available on https://5f2da7b5.aosankaku-website-2025.pages.dev/blog/gatsby-graphql-override/ and this is build based on AoSankaku/aosankaku-website-2025@730b617 . Note that the syntax highlighing is disabled just because I forgot to change the syntax of the code block title, it worked fine.

3 replies

delucis Dec 18, 2025
Maintainer

I think your solution is OK. When useDarkModeMediaQuery is enabled it uses a CSS @media query which can’t respond to a custom theme toggle in your site, so it is expected that you need to add a data- attribute for Expressive Code to respond to.

AoSankaku Dec 18, 2025
Author

So, in short, is it impossible to simply toggle code block light/dark theme by just modifying astro.config.mjs in Astro projects (Expressive Code does not "watch" the css @media query toggle)?

delucis Dec 18, 2025
Maintainer

Expressive Code can watch the @media. But your website is not using a media query for dark mode. It uses a custom class="dark" on the <html> element.

You could use the themeCssSelector option though to avoid the extra JS you have. For example something like:

themeCssSelector: (theme) => theme.type === 'dark' ? '.dark' : '.light',

hippotastic · 2025-12-19T10:57:10Z

hippotastic
Dec 19, 2025
Maintainer

In my opinion, the issue is that you're using a light theme as the default on your site (without any dark class on the html element, your site is light), but the order of your themes in the EC config lists the dark theme as the default (the first theme is the default theme).

You need to change the order of themes in your EC config so that it matches your site setup. The light theme needs to come first.

In addition, you need to configure the themeCssSelector as suggested by delucis so that it also reacts to the dark class.

0 replies

AoSankaku · 2025-12-20T08:17:50Z

AoSankaku
Dec 20, 2025
Author

OK, after research (and with help by Gemini because my English is not so good), I managed to solve this with:

    themes: ['one-light', 'one-dark-pro'],
    useDarkModeMediaQuery: false,
    themeCssSelector: (theme, { styleVariants }) => {
      // 2. If the theme is 'one-dark-pro', trigger it when .dark class is on <html>
      if (theme.name === 'one-dark-pro') return '.dark';
      // Otherwise, it's the default theme (one-light)
      return false;
    },

And the crucial concepts are:

The first theme is the default theme. The order absolutely matters.
useDarkModeMediaQuery must be disabled in order not to let EC respond to @media query (This is the very first time to implement light/dark theme toggle in my website, so I still haven't understood how @media query is related to this problem, and the way EC expects me to set light/dark/theme attributes).
The function in themeCssSelector should return the class name indicating the current theme, and theme.name means element in themes used in for function part internally (maybe?). The function should return false or something to use the default value.

May I update the docs ( https://github.com/expressive-code/expressive-code/tree/main/docs ) and create pull request to pubilsh this guide for following beginners? If any of the hints are incorrect even partially, tell me as soon as possible. Thank you again for very quick and helpful responses!

1 reply

hippotastic Dec 20, 2025
Maintainer

I'm glad we could help. Thank you for outlining your solution in detail - this can be very useful for others with a similar use case and site configuration.

I agree that the documentation could be improved - we could use some examples for typical theme switcher setups along with the matching EC configuration.

The current explanation on how EC's theme CSS generation works is probably not visible enough as it's located in the core API section of the docs: https://expressive-code.com/reference/core-api/#getthemestyles

As explained in this section, EC always generates CSS variables for the "base theme" (= the first theme in the themes array).

If useDarkModeMediaQuery has not been manually set to false, it will also generate a media query that switches to the first theme of the opposite type if the user prefers that theme type. For example, if the base theme is a dark theme, it will generate a media query that switches the code blocks to the first light theme if the user prefers light themes.

Also, EC will go through all other themes in the themes array and create differential sets of CSS variables for them as long as themeCssSelector returns a truthy value for the respective theme. It will then generate a CSS selector using the themeCssRoot and return value of themeCssSelector to allow manually selecting this theme. If themeCssSelector is not set, EC will create a selector that matches the data-theme attribute set to the name of the theme to allow selecting any theme in your themes array by name.

What you're doing when customizing themeCssSelector to something like delucis' example...

themeCssSelector: (theme) => theme.type === 'dark' ? '.dark' : '.light',

...is that you're telling EC "I don't want to select the themes by their name, I want to use the classes dark and light instead". Note that this customization only allows selecting up to 2 themes (one dark, and one light theme), while EC's default approach using the theme names works with any amount of themes in the themes array.

Also, note that returning false from the themeCssSelector function does NOT mean "use the default approach to build a selector for this theme". Actually, false means "I don't need to be able to select this theme manually", which completely skips selector-based CSS generation for this theme. The only way this theme could be displayed is if EC's media query determines that it's the proper theme to display for the user's preference. This is also explained here: https://expressive-code.com/reference/configuration/#themecssselector

To your question regarding useDarkModeMediaQuery, here's why you had to disable it on your site given your config:

EC displays the base theme by default. On your site, after correcting the themes array order, this is the light theme.
On your site, given your theming JS code, there are two cases in which the dark theme could be displayed instead:
a) when useDarkModeMediaQuery has not been turned off, and the user prefers to see dark themes.
b) when, based on your themeCssSelector function, there's a dark class on the html element because the user manually switched to a dark theme.

Note that the logic above is missing a case (c) "although the user generally prefers to see dark themes, they manually switched the site to a light theme". Because you don't have a CSS class in your JS code to identify this scenario, these conditions would trigger case (a) and incorrectly display a dark code block theme. You can prevent this by either turning useDarkModeMediaQuery off (thereby removing case (a)), or changing your JS code to also set a light CSS class on the html element in case a light theme was selected manually (thereby adding the missing case (c)). If you combine this with delucis' themeCssSelector above, you could keep useDarkModeMediaQuery on, which has the nice benefit that it displays the user-preferred theme even if JS has been turned off.

I hope I could clarify the workings of EC's theming logic a bit. This is a complex matter, and the exact configuration depends very much on the individual site's requirements, so I'm afraid it's hard to write easy-to-follow docs for this. In case you or anyone else reading this feels up to the task to improve docs on this matter, PRs are always welcome.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Dark/Light theme toggle is not working at all in my Astro project #410

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 4 comments 4 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Dark/Light theme toggle is not working at all in my Astro project #410

Uh oh!

Uh oh!

AoSankaku Dec 17, 2025

Tried solutions

Current problematic code

astro.config.mjs

Layout.astro

BlogArticleLayout.astro

Resources

Problematic website

Repository

Replies: 4 comments · 4 replies

Uh oh!

delucis Dec 18, 2025 Maintainer

Uh oh!

AoSankaku Dec 18, 2025 Author

Uh oh!

delucis Dec 18, 2025 Maintainer

Uh oh!

AoSankaku Dec 18, 2025 Author

Uh oh!

delucis Dec 18, 2025 Maintainer

Uh oh!

hippotastic Dec 19, 2025 Maintainer

Uh oh!

AoSankaku Dec 20, 2025 Author

Uh oh!

hippotastic Dec 20, 2025 Maintainer

AoSankaku
Dec 17, 2025

Replies: 4 comments 4 replies

delucis
Dec 18, 2025
Maintainer

AoSankaku
Dec 18, 2025
Author

delucis Dec 18, 2025
Maintainer

AoSankaku Dec 18, 2025
Author

delucis Dec 18, 2025
Maintainer

hippotastic
Dec 19, 2025
Maintainer

AoSankaku
Dec 20, 2025
Author

hippotastic Dec 20, 2025
Maintainer