Implementing a light/dark mode toggle with app router + RSC #53063

altano · 2023-07-23T05:07:31Z

altano
Jul 23, 2023

It is extremely difficult to implement a light/dark mode toggle with app router + RSC. People are stumbling over every piece of the puzzle and there are numerous issues/discussions about the problems the different approaches have. If this is already possible, it would be great if we could get an official example to serve as a reference implementation. And if not, could we get the bugs fixed that block such a reference implementation?

The requirements that make this hard are as follows:

There should NOT be a flash of the wrong mode on page load. It should be light/dark right away, on first render.
The user should be able to override light/dark with a toggle button. Only using media queries to target the system light/dark state isn't good enough.
The solution should not block rendering UI until the React app is hydrated and renders, e.g. using tricks where the html is display:none until the React component renders. The only JS that blocks render should be the few lines of JS we inline into the <head> that sets the light/dark mode attribute on html.
There should be no terminal or browser errors, neither during the server component render nor during the render of any of the React components in the browser.
The first time we render the light/dark mode toggle on the client it should already be in the correct state. Since that can't be determined on the server, this component will have to flash in on the client, not part of the server side render.

Here's a summary of the issues I'm aware of:

We must run some JS to detect the system color mode and set a class/data attribute/something on page load, as early as possible, before any UI renders. With the page router we could reliably inject scripts into the <head> but I don't see a way to do that with the app router. <Script> does not run early enough, not even with beforeInteractive. There are threads where people have claimed that <script> will load at the bottom of head, but I am not observing that. In short: how do we reliably inject a few lines of JS into the head, in both production and development builds? Example threads:
The app router hydrates at the documentElement (html) so any solution to the above will result in hydration warnings. The only solution to this seems to be using suppressHydrationWarning which feels like a pretty heavy hammer and can potentially cause us to miss other real issues that get suppressed. Example threads:
- Any <Script /> with strategy="beforeInteractive" in RootLayout causes hydration errors #51242
- (AppDir) Hydration error in dev mode when using inline <script /> tag #44366
Once you have the JS inlined into the head that does the first pass at setting the html attribute, you still need a proper React component to take over that state and update the html attribute accordingly. It is pretty hard to create an isomorphic component that does nothing on server render but then sets the html attribute once it is hydrated. For example, dynamically loading with ssr:false makes it easy to write an isomorphic component, but the component loads too late and there are bugs with dynamically loaded content.

There are a lot of solutions floating around but I haven't found one that actually meets the requirements above. For example:

This solution hides all content from the documentElement until the React app runs (which completely negates the gains of RSC and server-side rendering).
This solution relies on the Accept-CH header, but that doesn't work on first load and isn't supported by Firefox/Safari.
etc...

olliejm · 2023-07-26T16:08:45Z

olliejm
Jul 26, 2023

This meets your requirements 1-4 (and maybe 5), as long as your theme CSS can be controlled by data-theme or some other attribute.

src/app/layout.tsx

import { cookies } from 'next/headers';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const cookieStore = cookies();
  const theme = cookieStore.get('theme'));
  return (
    <html lang="en" data-theme={theme?.value}>
      <body>
        <ThemeToggle initialValue={theme?.value as ('light' | 'dark')} />
        {children}
      </body>
    </html>
  );
}

src/components/client/ThemeToggle.tsx

'use client';

import { useEffect, useState } from 'react';

type Theme = 'light' | 'dark';

function ThemeToggle({ initialValue }: { initialValue: Theme }) {
  const [theme, setTheme] = useState(initialValue);

  useEffect(() => {
    if (theme) {
      document.cookie = `theme=${theme};path=/;`;
      document.querySelector('html').setAttribute('data-theme', theme);
    } else {
      setTheme(window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
    }
  }, [theme]);

  return (
    <button type="button" onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
      Toggle Theme
    </button>
  );
}

export default ThemeToggle;

I'm not sure if it is the best way but it worked for me. The main problem to be overcome is that when the user picks a theme it needs to be known on the server to avoid the potential FOUC when data-theme is empty in RSC/SSR output and then becomes initialised by the client - if the user has set a theme which is different to system default.

This overcomes that, the main problem I guess is whether using a cookie for it is the "right" way, or maybe you need to avoid cookies.

There's one caveat I noticed which relates to your 5th requirement, which is present in my actual use case but not in the demo above: when initialValue is empty on the first page view, if you want to e.g. conditionally render an icon for the button, and the user's default theme is different to the default pre-cookie value on the server, you will get a FOUC still of the icon.

You could return null or some loading state until the effect runs and the theme has a value to avoid that.

4 replies

zaynelovecraft Jan 22, 2024

Is it now possible for all routes to be server-side rendered since cookies are being accessed in the root layout of your application? While it may be beneficial to have pre-built static pages, SSR can be useful in knowing the user's preferred theme when building a page on the server. However, is it possible to still generate static pages while accessing the cookie in middlewares and making changes to the HTML document before sending it to the user? This could potentially allow for all pages to remain static by default.

olliejm Jan 22, 2024

This solution would make all pages dynamically rendered because of the cookie access yeah, for a better option see the other comments on this issue. For my purposes I did not at the time need any non-dynamic pages, and was lacking enough familiarity with Next 13 to realise this would not be a good option for a lot of cases.

zaynelovecraft Jan 22, 2024

I think we can use middleware to access the cookie and set the classname to the theme before html document is sent to user. this will keep the pages static

Also below solution does not work for knowing users theme setting on the server..

magnusriga Sep 26, 2024

@zaynelovecraft Thanks for the inspiration here. Would you somehow change the stylesheet's root CSS variables, from middleware, after reading cookies, or how would you go about getting the cookie theme into the code, when pages are statically rendered?

Hugomndez · 2023-09-14T02:07:08Z

Hugomndez
Sep 14, 2023

Example Live Site URL : https://nextjs-app-darkmode.vercel.app/
Example Solution URL: https://github.com/Hugomndez/nextjs-app-darkmode

This solution by Dan Abramov meets most of the requirements.

src/lib/getTheme.js

const code = function () {
  window.__onThemeChange = function () {};

  function setTheme(newTheme) {
    window.__theme = newTheme;
    preferredTheme = newTheme;
    document.documentElement.dataset.theme = newTheme;
    window.__onThemeChange(newTheme);
  }

  var preferredTheme;

  try {
    preferredTheme = localStorage.getItem('theme');
  } catch (err) {}

  window.__setPreferredTheme = function (newTheme) {
    setTheme(newTheme);
    try {
      localStorage.setItem('theme', newTheme);
    } catch (err) {}
  };

  var darkQuery = window.matchMedia('(prefers-color-scheme: dark)');

  darkQuery.addEventListener('change', function (e) {
    window.__setPreferredTheme(e.matches ? 'dark' : 'light');
  });

  setTheme(preferredTheme || (darkQuery.matches ? 'dark' : 'light'));
};

export const getTheme = `(${code})();`;

src/app/layout.tsx

import './globals.css';
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';

import { getTheme } from '../lib/getTheme';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang='en'>
      <head>
        <script dangerouslySetInnerHTML={{ __html: getTheme }} />
      </head>
      <body className={inter.className}>{children}</body>
    </html>
  );
}

src/components/SetTheme.jsx

'use client';
import { useState, useEffect } from 'react';

const SetTheme = () => {
  const [theme, setTheme] = useState(global.window?.__theme || 'light');

  const isDark = theme === 'dark';

  const toggleTheme = () => {
    global.window?.__setPreferredTheme(theme === 'light' ? 'dark' : 'light');
  };

  useEffect(() => {
    global.window.__onThemeChange = setTheme;
  }, []);

  return <button onClick={toggleTheme}>{isDark ? 'dark' : 'light'}</button>;
};

export default SetTheme;

src/app/page.tsx

import dynamic from 'next/dynamic';

const SetTheme = dynamic(() => import('../components/SetTheme'), {
  ssr: false,
});

export default function Home() {
  return (
    <main>
      ...  
      <SetTheme />
      ...
    </main>
  );
}

globals.css

:root {
  color-scheme: light;
 ...
}

:root[data-theme='dark'] {
  color-scheme: dark;
 ...
}

Reference:

When developing React apps, we tend to do everything with React and put every logic inside React components. The experience of implementing themes reminds me it is okay to write code outside of the React world and later bind it to React. After all, React is just a library for building user interfaces. In this case, understanding how browser rendering works is essential to create a smooth user experience. by Hangindev

14 replies

Abilovv599 Mar 13, 2024

Thanks, helped a lot!

mririgoyen Apr 1, 2024

This doesn't seem to fully work. Error boundaries, such as not-found don't load the script, making the toggles error out and not appropriately adding the class to the html element. Anyone else seeing this?

abramchikd Apr 5, 2024

@mririgoyen
Pages like not found do not use app/layout.tsx. As I understand you should implement global-error.tsx and load script from there too https://nextjs.org/docs/app/building-your-application/routing/error-handling#handling-errors-in-root-layouts

mririgoyen Apr 5, 2024

While true, it's not entirely accurate. For example, the not-found error boundary DOES load the root app and layout template. However, what we've noticed is while it loads items in script tags into the DOM, it does not fully execute them when the site is loaded originating from a 404 page. I don't know how else to explain it, but I had to include, in our useEffect control, a check for the function on the window, and if it's isn't there, call the initial script again. It's not ideal, but it got around the immediate issue. I plan to put together a reproduction repo and report the larger bug within Next soon.

Aryan3902 Aug 24, 2024

Thanks for the typescript tips @hipstersmoothie , although when I am using window in some other file, (window.innerWidth in my case), I am getting the following error:

TypeError: _global_window.__setPreferredTheme is not a function

Is it happening maybe because the set window interface in theme context which is declared globally is getting override while mentioning window elsewhere?

christianonoh · 2024-01-02T10:50:33Z

christianonoh
Jan 2, 2024

@Hugomndez Thanks for sharing this. The idea of exporting the getTheme function as a string was brilliant.

0 replies

wwuinc · 2024-01-22T09:42:13Z

wwuinc
Jan 22, 2024

Great implementation for now...

0 replies

ceracera · 2024-03-24T19:45:09Z

ceracera
Mar 24, 2024

@Hugomndez thanks for this.
How can this be used if you need to get current theme? For example if you want to show different component for dark or light theme. How can you watch for current theme?

0 replies

HummingMind · 2024-07-08T06:33:28Z

HummingMind
Jul 8, 2024

None of these solutions are "clean", they all either happen too late or they all use suppressHydrationWarning (which is less than ideal). 😞

Hoping for a cleaner solution from the Next.js team. 🍻

0 replies

Mandaline · 2024-07-18T13:46:58Z

Mandaline
Jul 18, 2024

Using the cookies answer above as a base, I think I found a relatively simple solution to this issue, adding in React Context. We can include a Context Provider in the layout and still have all the children be server or client components, as only the children that consume the context need to be client components. Without context, my toggle button would flicker on page load and route changes. I'm using data-theme and CSS variables with Tailwind to manage the styles, and I'm sourcing the initial theme from my CMS (overriding this if a user has visited the site and chosen their theme).

Full solution and example site here: https://www.mandalinedev.com/articles/color-themes-next-js

// src/app/layout.tsx

export default async function RootLayout({ children }: RootLayoutProps ) {
  const client = createClient();
  const settings = await client.getSingle("settings");
  const cookieStore = cookies();
  const theme = cookieStore.get('theme');

  return (
    <html
      lang="en"
      className={`${nunito_sans.className} ${fira_mono.className}`}
      data-theme={theme?.value ?? settings.data.theme}
    >
      <body className="overflow-x-hidden antialiased">
        <main>
          <ThemeProvider initialTheme={theme?.value ?? settings.data.theme}>
            {children}
          </ThemeProvider>
        </main>
      </body>
    </html>
  );
}

// src/app/theme-provider.tsx

'use client';

import { createContext, useState, ReactNode, useEffect } from 'react';
import { setCookie } from 'cookies-next';

interface ThemeContextType {
  theme: string;
  setTheme: (theme: string) => void;
}

export const ThemeContext = createContext<ThemeContextType>({
  theme: 'Turquoise',
  setTheme: () => {},
});

interface ThemeProviderProps {
  children: ReactNode;
  initialTheme: string;
}

export default function ThemeProvider({
  children,
  initialTheme
}: ThemeProviderProps) {
  const [theme, setThemeState] = useState(initialTheme);

  const setTheme = (newTheme: string) => {
    setThemeState(newTheme);
    setCookie('theme', newTheme, { path: '/', maxAge: 7 * 24 * 60 * 60 });
    document.documentElement.setAttribute("data-theme", newTheme);
  };

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

// ThemeToggle.tsx

'use client';

import { useContext } from "react";
import { ThemeContext } from "@/app/theme-provider";  

const themes = ["Turquoise", "Violet", "Purple"];

const ThemeSelector = () => {
  const { theme: selectedTheme, setTheme } = useContext(ThemeContext);

  const handleThemeChange = (theme: string) => {
    setTheme(theme);
  };

  const classNames = (...classes: string[]) => {
    return classes.filter(Boolean).join(' ');
  };

  return (
    <div>
      <nav className="flex space-x-4" aria-label="Tabs">
        {themes.map((theme) => (
          <button
            key={theme}
            onClick={() => handleThemeChange(theme)}
            className={classNames(
              selectedTheme === theme
                ? 'text-highlight-light bg-secondary-dark'
                : 'text-primary-light hover:text-highlight-light',
              'transition-colors rounded-lg px-4 py-1 text-sm tracking-tight'
            )}
            aria-current={selectedTheme === theme}
          >
            {theme}
          </button>
        ))}
      </nav>
    </div>
  );
};

export default ThemeSelector;

2 replies

codenomnom Sep 23, 2024

Beware that using cookies in your layout will make pages render dynamically.

magnusriga Sep 26, 2024

Beware that using cookies in your layout will make pages render dynamically.

I'm facing the same issue. Having the entire app become dynamic is an absolute no-go in most cases. Among other consequences, it defeats the entire purpose of Partial Pre-Rendering, meaning that none of the app's components are now going to be statically rendered.

Crsk · 2025-01-26T00:41:11Z

Crsk
Jan 26, 2025

There's an abstraction worth considering that deals mostly with all of these requirements. Here https://www.npmjs.com/package/next-themes

0 replies

sousounibajis · 2025-03-19T08:50:32Z

sousounibajis
Mar 19, 2025

Hi everyone,

I wanted to share a simplified version of how I ended up implementing a light/dark mode toggle in a Next.js App Router + RSC project, inspired by next-app-theme but adapted to use sessionStorage (and avoid cookies or localStorage). Below is a single code block showing the essential pieces—our custom inline script, a useTheme hook, and a minimal toggle example. The main idea is that we store the theme in sessionStorage and force a full page reload when switching locales, so that the script runs fresh and applies the correct theme immediately.

//
// 1) SessionThemeScript.tsx
//
//  Inline script that runs in <head> to set the theme from sessionStorage
//  (or system preference if nothing is stored).
//

// src/components/SessionThemeScript.tsx
import React from "react";

type Theme = "dark" | "light";

declare global {
  interface Window {
    __theme: Theme;
    __onThemeChange: (theme: Theme) => void;
    __setPreferredTheme: (theme: Theme) => void;
  }
}

const code = function () {
  // Declare sessionStorageKey inside the function.
  const sessionStorageKey = "__PREFERRED_THEME__";
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
  window.__onThemeChange = function (theme) {};

  function setTheme(newTheme: Theme) {
    if (window.__theme) {
      document.documentElement.classList.remove(window.__theme);
    }
    window.__theme = newTheme;
    document.documentElement.dataset.theme = newTheme;
    window.__onThemeChange(newTheme);
    document.documentElement.classList.add(newTheme);
  }

  let preferredTheme: Theme | null = null;
  try {
    preferredTheme = sessionStorage.getItem(sessionStorageKey) as Theme | null;
    console.log("Read preferredTheme from sessionStorage:", preferredTheme);
  } catch (_err) {
    console.error("Error reading sessionStorage:", _err);
  }

  window.__setPreferredTheme = function (newTheme: Theme) {
    setTheme(newTheme);
    try {
      sessionStorage.setItem(sessionStorageKey, newTheme);
      console.log("Updated sessionStorage with theme:", newTheme);
    } catch (_err) {
      console.error("Error setting sessionStorage:", _err);
    }
  };

  const darkQuery = window.matchMedia("(prefers-color-scheme: dark)");
  darkQuery.addEventListener("change", function (e) {
    window.__setPreferredTheme(e.matches ? "dark" : "light");
  });

  const computedTheme: Theme = preferredTheme || (darkQuery.matches ? "dark" : "light");
  console.log("Computed theme:", computedTheme);
  setTheme(computedTheme);
  if (!preferredTheme) {
    try {
      sessionStorage.setItem(sessionStorageKey, computedTheme);
      console.log("Stored computed theme in sessionStorage:", computedTheme);
    } catch (_err) {
      console.error("Error storing computed theme in sessionStorage:", _err);
    }
  }
};

const getTheme = `(${code})();`;

export function SessionThemeScript() {
  return <script dangerouslySetInnerHTML={{ __html: getTheme }} />;
}


//
// 2) useTheme.ts
//
//  A custom hook that reads the current theme from window.__theme,
//  provides a toggle function, and re-reads sessionStorage on route changes.
//


// src/lib/use-theme.ts
|
"use client"

import { useCallback, useEffect, useState } from "react"
import { usePathname } from "next/navigation"

export function useTheme() {
  const pathname = usePathname()
  const [theme, setTheme] = useState(
    typeof window === "undefined" ? "light" : window.__theme || "light",
  )

  const toggleTheme = useCallback(() => {
    // Read the current theme directly from the global variable.
    const current = window.__theme || "light"
    const newTheme = current === "light" ? "dark" : "light"
    console.log("Toggling theme: current =", current, ", new =", newTheme)

    // Use the fallback mechanism for setting the theme.
    if (typeof window.__setPreferredTheme === "function") {
      window.__setPreferredTheme(newTheme)
    } else {
      console.warn("window.__setPreferredTheme is not a function")
      sessionStorage.setItem("__PREFERRED_THEME__", newTheme)
      document.documentElement.setAttribute("data-theme", newTheme)
    }

    // Force a re-read from sessionStorage immediately after toggling.
    try {
      const stored = sessionStorage.getItem("__PREFERRED_THEME__")
      if (stored) {
        console.log("After toggle, stored theme =", stored)
        setTheme(stored as "light" | "dark")
      } else {
        // Fallback if nothing is stored.
        setTheme(newTheme)
      }
    } catch (err) {
      console.error("Error reading sessionStorage after toggle:", err)
      setTheme(newTheme)
    }
  }, [])

  useEffect(() => {
    // Register callback so that whenever the inline script updates the theme, we update our local state.
    window.__onThemeChange = newTheme => {
      console.log("Global theme changed to:", newTheme)
      setTheme(newTheme)
    }
  }, [])

  // On every route change, re-read sessionStorage.
useEffect(() => {
  if (typeof window !== "undefined") {
    const stored = sessionStorage.getItem("__PREFERRED_THEME__")
    if (stored && stored !== theme) {
      console.log("Route change: updating theme from sessionStorage:", stored)
      if (typeof window.__setPreferredTheme === 'function') {
        window.__setPreferredTheme(stored as "light" | "dark")
      } else {
        console.warn("window.__setPreferredTheme is not a function")
        document.documentElement.setAttribute("data-theme", stored)
      }
      setTheme(stored as "light" | "dark")
    }
  }
  // eslint-disable-next-line react-hooks/exhaustive-deps
}, [pathname])

  return { theme, toggleTheme }
}


//
// 3) ThemeToggle.tsx
//
//  A toggle component that calls the hook to switch
//  between light and dark modes.
//

// src/components/ThemeToggle.tsx
"use client"

import { useEffect, useState } from "react"
import { Moon, Sun } from "lucide-react"
import { useTheme } from "@/lib/theme/use-theme"
import { Button } from "./ui/button"

export default function ThemeToggle() {
  const { theme, toggleTheme } = useTheme()
   const [mounted, setMounted] = useState(false)
  
   useEffect(() => {
    setMounted(true)
  }, [theme])

  if (!mounted) return null
    const icon = theme === "dark" ? <Sun size={18} className="text-zinc-800 dark:text-off-white" /> : <Moon size={18} className="text-zinc-800 dark:text-off-white" />
  return (
    <Button
      onClick={toggleTheme}
      aria-label="Toggle Dark Mode"
      className="hover:scale-105 transition-all duration-300 cursor-pointer"
      variant="outline-no-bg"
      size="sm"
    >
      {icon}
    </Button>
  )
}

//
// 4) "Locale Switcher" snippet
//
//  Before switching locales, store the current theme in sessionStorage,
//  then force a full page reload so the inline script re-applies the theme.
//

"use client";

import { useTransition } from "react";
import { setUserLocale } from "@/i18n/action"
import { useLocale } from "next-intl";
import { useRouter } from "next/navigation";

export function LocaleSwitcher() {
  const router = useRouter();
  const [isPending, startTransition] = useTransition();
  const currentLocale = useLocale();

  function handleChange(value: string) {
    if (value === currentLocale || isPending) return
    if (typeof window !== "undefined" && window.__theme) {
      sessionStorage.setItem("__PREFERRED_THEME__", window.__theme)
    }
    startTransition(async () => {
      await setUserLocale({ id: value } as Locale)
      const currentUrl = new URL(window.location.href)

      const pathSegments = currentUrl.pathname.split("/").filter(Boolean)
      if (pathSegments.length > 0) {
        pathSegments[0] = value
      } else {
        pathSegments.push(value)
      }
      currentUrl.pathname = "/" + pathSegments.join("/")
      window.location.assign(currentUrl.toString())
      router.refresh()
    })
  }
  return (
    <select onChange={(e) => handleChange(e.target.value)} value={currentLocale}>
      <option value="en">English</option>
      <option value="ar">Arabic</option>
      {/* etc. */}
    </select>
  );
}

//
// 5) A `ClientOnly` component 
//
// Injects the inline theme script into the <head>—the theme gets applied
// on first load (and re-applied when locales change).


// src/components/ClientOnly.tsx

"use client";

import React, { useState, useEffect } from "react";

export function ClientOnly({ children }: { children: React.ReactNode }) {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted) return null;
  return <>{children}</>;
}

//
// 6) The root layout
//

// src/app/layout.tsx

// SessionThemeScript is injected into <head>
// ClientOnly wraps the children for client-side rendering

import { SessionThemeScript } from "@/components/SessionThemeScript";
import ClientOnly from "@/components/ClientOnly"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <SessionThemeScript />
      </head>
      <body>
        <ClientOnly>
          {children}
        </ClientOnly>
      </body>
    </html>
  );
}

5 replies

sousounibajis Mar 19, 2025

How It Works

The inline script (SessionThemeScript) runs in the <head> of our layout, reading the theme from sessionStorage and applying it immediately—so there's minimal flashing.
The ClientOnly component wraps parts of the app that relies on client-side logic (the theme hooks). The components using browser-specific features only render after hydration to prevent mismatches between server and client.
The useTheme hook updates its local state from the global variables and re-checks sessionStorage whenever the route changes (for instance, on a locale switch).
The ThemeToggle component calls toggleTheme, which updates both the DOM and sessionStorage.
The locale switcher saves the current theme and then forces a full reload (rather than a client‑side navigation) so that the inline script runs again on the new locale page (optional)

Additional note on CSS Rules for .light and .dark classes

The following CSS rules were added to the globals.css to set the browser’s color scheme:

.light {
  color-scheme: light;
}
.dark {
  color-scheme: dark;
}

GabenGar Mar 20, 2025

This requires all pages to be client-rendered, which defeats the point of using nextjs and app router specifically.

sousounibajis Mar 21, 2025

@GabenGar, instead of wrapping the entire layout with a ClientOnly component, remove that wrapper from the root layout. Then, wrap where you call the theme toggle component in the ClientOnly since it requires browser APIs (sessionStorage, window, etc.).

This way, the inline theme script in the head runs as early as possible to set the correct theme, while the rest of the layout benefits from SSR. Note that the locale switcher still saves the theme in sessionStorage and forces a full reload on locale change—if needed—so that the inline script re‑runs. The locale switcher is optional in this solution, depending on your UX needs.

Hope this helps clarify the approach.

sousounibajis Mar 21, 2025

Updated code:

If you don't want your pages to be client-rendered (requiring all pages to be client‑rendered through the root layout), modify the solution as follows:

1. Remove the ClientOnly wrapper from the root layout:
This allows the majority of the page to be server‑rendered. The updated layout now looks like:

// src/app/layout.tsx
import { SessionThemeScript } from "@/components/SessionThemeScript";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <SessionThemeScript />
      </head>
      <body>
          {children}
      </body>
    </html>
  );
}

2. Wrap only the ThemeToggle in ClientOnly within the header:
Since the theme toggle requires access to browser-specific APIs (like sessionStorage and window), wrap it in a ClientOnly component in your header where where you make the call to theme toggle. or example:

// src/components/header.tsx
import React from "react";
import dynamic from "next/dynamic";
import { LocaleSwitcher } from "@/components/LocaleSwitcher";
import ClientOnly from "@/components/ClientOnly";

// Dynamically import ThemeToggle (client-side only)
const ThemeToggle = dynamic(() => import("./ThemeToggle"), {
  ssr: false,
  loading: () => <div className="w-9 h-9" />,
});

export default function Header({ user }) {
  return (
    <header>
      <div className="flex items-center justify-between">
        {/* Other header elements such as Logo, Navigation, etc. */}
        <div className="flex items-center gap-4">
          <LocaleSwitcher />
          <ClientOnly>
            <ThemeToggle />
          </ClientOnly>
          {user ? <UserDropdown user={user} /> : <ButtonLogin />}
          {!user && <ButtonSignup />}
        </div>
      </div>
    </header>
  );
}

For those already following this solution, you can update your code as shown above.

sousounibajis Apr 30, 2025

UPDATE (April 30): Hydration-safe alternative using external script

Following up on this implementation, I wanted to share a cleaner, hydration-safe alternative to using SessionThemeScript.tsx. The reason for this update is simple: using dangerouslySetInnerHTML in the <head> can potentially introduce hydration mismatches, especially in server-rendered React apps.

This updated method avoids that by moving theme initialization into a static external script (theme-init.js) and loading it via Next.js’s <Script strategy="beforeInteractive" />. It’s safer, runs earlier, and keeps your React tree clean..

You can either:

Stick with the original inline <SessionThemeScript />, OR
Switch to a safer, next/script-based solution using an external JS file to avoid hydration mismatches from your own code

What to do

Just 3 simple steps:

1 Create this file:

// public/theme-init.js
;(function () {
  const sessionStorageKey = "__PREFERRED_THEME__"

  function setTheme(theme) {
    document.documentElement.classList.remove("light", "dark")
    document.documentElement.classList.add(theme)
    document.documentElement.dataset.theme = theme
    try {
      sessionStorage.setItem(sessionStorageKey, theme)
    } catch (e) {
      console.warn("Unable to set theme in sessionStorage:", e)
    }
  }

  try {
    let preferredTheme = sessionStorage.getItem(sessionStorageKey)
    const systemPrefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches
    const theme = preferredTheme || (systemPrefersDark ? "dark" : "light")

    setTheme(theme)

    const darkQuery = window.matchMedia("(prefers-color-scheme: dark)")
    function handleSystemChange(e) {
      const newTheme = e.matches ? "dark" : "light"
      setTheme(newTheme)
      window.__theme = newTheme
      if (typeof window.__onThemeChange === "function") {
        window.__onThemeChange(newTheme)
      }
    }
    darkQuery.addEventListener("change", handleSystemChange)

    window.__theme = theme
    window.__onThemeChange = function () {}
    window.__setPreferredTheme = function (newTheme) {
      setTheme(newTheme)
      window.__theme = newTheme
      if (typeof window.__onThemeChange === "function") {
        window.__onThemeChange(newTheme)
      }
    }
  } catch (e) {
    console.error("Theme init failed:", e)
  }
})()

2 Delete this file:

src/components/SessionThemeScript.tsx

It’s no longer needed.

3 Update your `layout.tsx`:

Replace this:

import { SessionThemeScript } from "@/components/SessionThemeScript";

With this:

import Script from "next/script";

And update your layout like so:

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <Script src="/theme-init.js" strategy="beforeInteractive" />
      </head>
      <body>
        {children}
      </body>
    </html>
  );
}

If using localized paths, make sure to update the matcher in middleware.ts to exclude static file extensions (.js) so files like theme-init.js aren’t incorrectly redirected to localized paths like /en/theme-init.js. e.g.

export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|site.webmanifest|api/auth|api/support-checkout|.*\\.js|.*\\.css).*)",
  ],
};

Notes

Eliminates the use of dangerouslySetInnerHTML
Avoids potential hydration mismatch issues in your code
Executes before React hydration using strategy="beforeInteractive"
Works well with App Router and SSR
Cleaner separation via a standalone script
If you're seeing hydration warnings, especially in Chromium browsers, it's likely caused by browser extensions modifying the DOM — this method won’t fix those, and no code can.

This script-based approach is now my recommended way to apply a persisted theme early without risking React hydration mismatches.

kabledev · 2025-03-24T04:38:00Z

kabledev
Mar 24, 2025

I've shared an example of an application that works well for me. I'm not sure if there's a better approach, but this solution works smoothly for now:
Next.js-SSR-Supported-Theme-Toggle

0 replies

Implementing a light/dark mode toggle with app router + RSC #53063

Uh oh!

Uh oh!

Replies: 10 comments · 25 replies

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

What to do

1 Create this file:

2 Delete this file:

3 Update your layout.tsx:

Notes

Uh oh!

Replies: 10 comments 25 replies

3 Update your `layout.tsx`: