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.

3 replies

EpicDevv 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.

EpicDevv 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..

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

13 replies

hipstersmoothie Jan 7, 2024

I couldn't resist and I made it into a package 😄 https://www.npmjs.com/package/next-app-theme

Abilov599 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.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 5 comments 16 replies

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{title}}

Select a reply

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

Replies: 5 comments · 16 replies

Replies: 5 comments 16 replies