Add a Dark Mode Toggle to Your NextJS / React App (2024)

Using Components and CSS modules🌌

https://next-js-dark-mode.vercel.app/

🚀 Note: To complete this tutorial you will need to know how to setup and run a Node.js server, access the CLI, and how to use an IDE/text-editor to edit the files.

This is my first time writing an article, and also my first time writing a tutorial. It is my sincere hope that this tutorial proves useful and is easy to understand. Thanks for being here!

My name is Andrew Nelson — I’m a Full Stack Designer and Developer with over 20 years of professional and amateur experience🖖

I have tried my best to write this article / tutorial for beginners and experienced developers alike. If you are looking to learn as much as possible from this article, please start from here and take your time all the way through. I have tried to inject as much wisdom into this as I could.

For more experienced developers, I have included an index so you can fast travel to the content of your choice. I have also included an NPM command that will install this project and all the dependencies ↘— if you would prefer to just see the code in action.

The tutorial consists of the following sections 📑

• #1 — Install Next.js ↘
• #2 — Next.js Basic Folder Structure ↘
• #3 — Theme and Component CSS ↘
• #4 — Loading our CSS and Component ↘
• #5 — Theme.util.jsx Component ↘
  ◦ 1. Create the component and basic react hook
  ◦ 2. Set button styling and icon state
  ◦ 3. Check for default theme, and set the state
  ◦ 4. Watch for operating system theme changes
  ◦ 5. Preload a script and set the theme before hydration
• #6 — Putting it All Together ↘

Skip the tutorial and explore the working code 🚀

• Skip the Tutorial: Install the Finished App ↘

In this tutorial I will teach you to create and install a navigation style dark mode toggle 🦄

With everything that we craft, we should have the users experience at the top of mind. In this case I am trying to cater to two sets of users — the people using the app, and you, the developer making the app.

User Experience Considerations

• Theme selection must persist through page changes
• Theme selection must persist through separate sessions
• Theme selection is aware of current system settings
• Theme selection will live update if system settings is changed

Developer Experience Considerations

• I would like the entire module to be as self-contained as possible.
• The theme style sheet should be easy to read and edit.
• The theme color options should be centralized for a DRY styling experience.
• There should be no memory leaks or bugs in the source code.
• Code should be appropriately typed and named for readability, and comments used to explain more abstract code.
• Bonus: NPM instructions to install the completed tutorial.

Back to the Index 👆

Setup

First, let’s make sure that your development environment is ready.

• If you don’t have Node.js installed, install it from here. You’ll need Node.js version 10.13 or later.
• You’ll be using your own text editor and terminal app for this tutorial.

📑 Learn: If you are on Windows, we recommend downloading Git for Windows and use Git Bash that comes with it, which supports the UNIX-specific commands in this tutorial. Windows Subsystem for Linux (WSL) is another option.

Create a Next.js app

To create a Next.js app, open your terminal, cd into the directory you’d like to create the app in, and run the following command:

npx create-next-app@latest nextjs-dark-mode --use-npm --example "https://github.com/vercel/next-learn/tree/master/basics/learn-starter"

Run the development server

You now have a new directory called nextjs-dark-mode. Let’s cd into it:

cd nextjs-dark-mode

Then, run the following command:

npx run dev

This starts your Next.js app’s “development server” on port 3000.

Let’s check to see if it’s working. Open http://localhost:3000 from your browser.

Continue learning Next.js 🚀🥳

This tutorial is built on Vercel’s Learn Next.js free mini-course. I highly recommend continuing on with their course if you want to learn more about Next.js.

Back to the Index 👆

/pages/

This is where all your sites pages go. Next.js automatically takes care of the routing. So if you add a /portfolio/ folder and an index.jsx to it then it will automatically create the URL for you — yoursite.com/portfolio/.

/styles/

This is where Next.js suggests all your style sheets live. I have not tested if anything breaks if this gets renamed. If you know more about this please let us know in the comments.

/components/

This is where all your React components will live, and this is where we will be spending the majority of our time in this tutorial!

Back to the Index 👆

To make developing the different themes / states as simple as possible I have opted for a CSS Variable based color scheme.

The only major draw back of this system that I have come across is that you cannot use SCSS to modify the colors directly in the style sheets. This can be a nice feature, but for the most part I find it becomes inefficient and unwieldly the larger a project gets anyways.

The simple solution to that is just to add some extra color choices to your variables as needed.

⚠️ Important: All these style sheets go inside your /styles/ directory, and must be named exactly as they are titled.

variables.css

This is where all of the colors for your theme will be stored. We will be loading this file globally through the _app.jsx file.

global.css

The global CSS file that comes with this tutorial needs to be replaced with the following CSS.

theme.util.module.css

This is a dedicated CSS module that will only be used for the matching theme.util.jsx component. I will go over how to load that in the component section.

Back to the Index 👆

For the sake of simplicity in this tutorial we will be overriding the default _app.jsx page. This is a core structure that we can override by putting it in the /pages/ folder.

To do that create the _app.jsx file at /pages/_app.jsx.

To import our CSS we will use a basic import, and import both global CSS files we created above.

import '../styles/variables.css'
import '../styles/globals.css'

Next we are going to break the app — by importing a component we haven’t created yet (but will). I honestly thought about breaking this up into multiple sections to prevent any errors during the tutorial, but I’ll just have to plan better next time!

Lets import the theme.util.jsx and reference it as ThemeToggle.

import ThemeToggle from '../components/theme.util'

Then we will add the default _app.jsx module.

export default function MyApp({ Component, pageProps }) {
 return (
 <>
 <Component {...pageProps} />
 </>
 )
}

And finally we will add our <ThemeToggle /> module into the JSX.

export default function MyApp({ Component, pageProps }) {
 return (
 <>
 <ThemeToggle />
 <Component {...pageProps} />
 </>
 )
}

The _app.jsx file should now look like this.

Back to the Index 👆

This component is the core of our dark mode toggle. It controls the logic, the page state, the toggle button itself, and the JavaScript that will allows us to check what the current theme is, or what the users system theme is.

• 1. Create the component and basic react hook ↘
• 2. Set button styling and icon state ↘
• 3. Check for default theme, and set the state ↘
• 4. Watch for operating system theme changes ↘
• 5. Preload a script and set the theme before hydration ↘

1. Create the component and basic react hook

First we need to load the hooks from react with the follow import, and create our export module.

import { useState, useEffect } from "react"
export default function SetTheme() {
 return ()
}

Next we are going to add the variables that control the state.

• theme will contain the current state.
• setTheme will trigger a state change in the component and update the theme state.

import { useState, useEffect } from "react"
export default function SetTheme() {
 const [theme, setTheme] = useState()
 return ()
}

Finally we will integrate this into a button that controls the theme state by triggering the toggleTheme function onClick.

When the button is clicked, it runs the function toggleTheme and it will check the current theme and then set the new theme using setTheme.

💡 Idea: This could be coded more efficiently by using an Array and using Array.map to progress to the next array index in the loop. But for simplicity and readability I used an if else if statement.

const toggleTheme = () => {
 if ( theme == 'light') {
 setTheme('dark')
 } else if ( theme == 'dark' ) {
 setTheme('unicorn')
 } else if ( theme == 'unicorn' ) {
 setTheme('light')
 }
}
return (
 <>
 <button key="themeToggle" onClick={toggleTheme} >
 Change Theme
 </button>
 </>
)

The theme.util.jsx file should now look like this.

Back to the Index 👆

2. Set button styling and icon state

Now that we have our button and state control setup, lets make sure the button responds to the changes in state

To start lets import our components CSS module

import css from '../styles/theme.util.module.css'

Next we will add the buttonIcon function. This will return the <svg> to the button when the theme state changes.

const buttonIcon = () => {
 switch ( theme ) {
 case 'dark' : return ( <svg width="24" height="24" viewBox="0 0 24 24"><path d="M0 12c0 6.627 5.373 12 12 12s12-5.373 12-12-5.373-12-12-12-12 5.373-12 12zm2 0c0-5.514 4.486-10 10-10v20c-5.514 0-10-4.486-10-10z"/></svg> )
 case 'unicorn' : return ( <svg width="24" height="24" viewBox="0 0 24 24"><path d="M4.823 21.933l2.734-1.171-3.241-8.847-1.561 4.372 2.068 5.646zm-2.594-4.174l-2.229 6.241 3.903-1.672-1.674-4.569zm6.248 2.609l2.934-1.258-3.482-9.141-2.215-1.969-.872 2.443 3.635 9.925zm7.523-3.224l-6.453-5.736 2.785 7.308 3.668-1.572zm-.826-5.003l2.201-1.445c.23-.152.295-.462.143-.693-.152-.232-.463-.295-.692-.143l-2.201 1.445c-.231.151-.295.461-.144.692.096.147.256.226.418.226.095 0 .19-.026.275-.082m-2.993-4.312l1.112-2.388c.117-.25.008-.548-.242-.664-.251-.116-.548-.009-.665.242l-1.111 2.388c-.117.25-.008.547.242.664l.211.047c.189 0 .368-.107.453-.289m-2.627.709c1.539-2.963 1.644-5.73.314-8.222-.09-.169-.263-.265-.442-.265-.37 0-.621.398-.44.736 1.166 2.184 1.058 4.637-.32 7.29-.127.245-.031.547.214.674.073.038.152.057.23.057.18 0 .355-.099.444-.27m6.505 6.095c2.017-1.434 4.463-1.64 7.272-.613.327.119.672-.123.672-.47 0-.203-.125-.395-.328-.47-3.136-1.147-5.894-.9-8.196.738-.224.16-.277.472-.117.698.098.136.251.209.407.209.101 0 .202-.03.29-.092m3.757-6.757l-1.697.014.938 1.415-.511 1.618 1.635-.455 1.381.986.073-1.696 1.365-1.009-1.591-.592-.538-1.61-1.055 1.329zm-7.307 3.624c.276-.009.492-.24.483-.517-.056-1.627.36-1.937 1.377-2.051 1.689-.191 1.785-1.312 1.842-1.982.053-.637.071-.851.773-.903.63-.046 1.331-.16 1.76-.659.461-.538.466-1.358.402-2.164-.021-.276-.266-.478-.537-.459-.275.021-.481.262-.459.537.062.787.011 1.23-.165 1.434-.149.174-.48.271-1.074.314-1.553.114-1.644 1.179-1.697 1.816-.057.668-.082.973-.956 1.071-2.075.234-2.315 1.619-2.266 3.08.01.27.231.483.5.483h.017m7.842-8.675c0 1.006.818 1.824 1.825 1.824 1.006 0 1.824-.818 1.824-1.824 0-1.007-.818-1.825-1.824-1.825-1.007 0-1.825.818-1.825 1.825m-6.623-2.841c1.104 0 2 .897 2 2 0 1.104-.896 2-2 2-1.103 0-2-.896-2-2 0-1.103.897-2 2-2"/></svg> )
 case 'light' : return ( <svg width="24" height="24" viewBox="0 0 24 24"><path d="M12 0c-6.627 0-12 5.373-12 12s5.373 12 12 12 12-5.373 12-12-5.373-12-12-12zm4.95 5.636l1.414 1.414-2.195 2.195c-.372-.562-.853-1.042-1.414-1.414l2.195-2.195zm-5.95-1.636h2v3.101c-.323-.066-.657-.101-1-.101s-.677.035-1 .101v-3.101zm-3.95 1.636l2.195 2.195c-.561.372-1.042.853-1.414 1.415l-2.195-2.196 1.414-1.414zm-3.05 5.364h3.101c-.066.323-.101.657-.101 1s.035.677.101 1h-3.101v-2zm3.05 7.364l-1.414-1.414 2.195-2.195c.372.562.853 1.042 1.414 1.414l-2.195 2.195zm5.95 1.636h-2v-3.101c.323.066.657.101 1 .101s.677-.035 1-.101v3.101zm-1-5c-1.657 0-3-1.343-3-3s1.343-3 3-3 3 1.343 3 3-1.343 3-3 3zm4.95 3.364l-2.195-2.195c.562-.372 1.042-.853 1.414-1.414l2.195 2.195-1.414 1.414zm3.05-5.364h-3.101c.066-.323.101-.657.101-1s-.035-.677-.101-1h3.101v2z"/></svg> )
 }
 }

And lastly we will add 2 properties to the <button> to support the CSS and state of the button — data-theme={theme} and className={css.toggle}.

We will also need to add the buttonIcon(theme)function that passes the current theme as a parameter to return the current icon.

<button 
 key="themeToggle" 
 onClick={toggleTheme} 
 data-theme={theme} 
 className={css.toggle}
>
 { buttonIcon(theme) }
</button>

The theme.util.jsx file should now look like this.

⚠️ Important: for the sake of readability I have put placeholders where the SVG code for the icons go. There are references to the SVG code above, and in the Putting it All Together section.

Back to the Index 👆

3. Check for default theme, and set the state

3a. Check for a default theme value

We need to create a function that allows us to create a default theme selection. Will we use a saved value, or will we need to use the systems preferred value?

This is the defaultTheme() function.

const defaultTheme = () => {
 const themeLocalStorage = localStorage.getItem('theme')
 const themeSystem = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
 return ( themeLocalStorage ?? themeSystem )
}

• First we check the localStorage to see if a theme has been selected in a previous session.

const themeLocalStorage = localStorage.getItem('theme')

• Next we need to check the theme the system is set to, and then assign that to themeSystem.

const themeSystem = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'

• Then we will return the results of those prioritizing the localStorage data using the nullish coalescing (??) operator. If a theme selection has been stored in the local storage, we will use that, if not we will default to the systems theme.

return ( themeLocalStorage ?? themeSystem )

3b. Modifying the DOM with Reacts useEffect hook

To do this we have to make use of Reacts useEffect hook. Since we want this to run every time we update the theme we will be adding that variable to its dependencies array.

A very important factor of the useEffect hook is that it runs after every render. Meaning the first time it runs on our application, it wont have any user input — and the theme useState variable is only triggered by user input in this component.

useEffect( () => {
}, [theme] )

To capitalize on this architecture we are going to check to see if this is the first render, and if it is, we will set the theme to its default state using setTheme— and exit the function at the same time.

useEffect( () => {
 if ( ! theme ) return setTheme( defaultTheme() )
}, [theme] )

Because we just updated and set a theme, and it is a dependency of the useEffect hook, it will run again. This time around it will move past the if statement and run the rest of the code.

Now whenever we run this effect (in general that will be clicking the toggle) we can update the theme and set the current theme to the :root of the DOM, in this case the <HTML> element. We are also going to set the current theme to localStorage so the theme selection is saved between sessions.

useEffect( () => {
 if ( ! theme ) return setTheme( defaultTheme() )
 document.querySelector(':root').dataset.theme = ( theme )
 localStorage.setItem( 'theme', ( theme ) )
}, [theme] )

3c. The theme.util.jsx file should now look like this.

Back to the Index 👆

4. Watch for operating system theme changes

To watch for system theme changes in the operating system we are going to attach an event listener to the CSS media query we used to get the default theme preference earlier. We will also need to add the functionality to remove the eventListener in the effect hook.

4a. Building the event listener

We have to nest setTheme in another function so we can pass the eventListener response into it.

const useSetTheme = (e) => { setTheme( e.matches ? 'dark' : 'light' ) }

Next we will be assigning the element we want to attach the eventListener to a constant — so that we can unassign it to prevent memory leaks.

const watchSysTheme = window.matchMedia('(prefers-color-scheme: dark)')

Lets put all this together and complete our eventListener

const useSetTheme = (e) => { setTheme( e.matches ? 'dark' : 'light' ) }
const watchSysTheme = window.matchMedia('(prefers-color-scheme: dark)')
watchSysTheme.addEventListener( 'change', useSetTheme )

4b. Preventing memory leaks

I honestly don’t know the architecture of React hooks very well, so I don’t know how this code works, and how it ends up with only 1 eventListener, but it does 🥳

We return the removeEventListener at the end of the useEffect by returning it 🤷🏻

return () => {
 watchSysTheme.removeEventListener( 'change', useSetTheme )
}

4c. Putting it all together

useEffect( () => {
 if ( ! theme ) return setTheme( defaultTheme() )
 document.querySelector(':root').dataset.theme = ( theme )
 localStorage.setItem( 'theme', ( theme ) )
 const useSetTheme = (e) =>{ setTheme( e.matches ? 'dark' : 'light' ) }
 const watchSysTheme = window.matchMedia('(prefers-color-scheme: dark)')
 watchSysTheme.addEventListener( 'change', useSetTheme )
 return () => {
 watchSysTheme.removeEventListener( 'change', useSetTheme )
 }
}, [theme] )

4d. The theme.util.jsx file should now look like this.

Back to the Index 👆

5. Preload and set the theme before hydration

Using the Next’s script component next/script we are able to place a <Script> tag in our component. By giving it a specific parameter strategy="beforeInteractive" we can load and apply this script before the rest of the page is loaded through the Hydration event. This allows us to apply the theme data attribute immediately.

Next.js specifies that we should only use beforeInteractive in the _document.jsx page. However even though it will throw a linting error, it seems to be working as intended in this very specific use case.

This is JavaScript written in JSX syntax using the next/script module. We are using all the same JavaScript as we did before to make this happen.

<Script id="theme.util.jsx" strategy="beforeInteractive" >
 {`
 let themeLocalStorage = localStorage.getItem('theme')
 let themeSystem = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
 document.querySelector(':root').dataset.theme = themeLocalStorage ?? themeSystem
 `}
</Script>

We will simply add this to the JSX we are returning from the main method, right above our button, and our utility component is now complete.

The finished theme.util.jsx file should now look like this. 🥳

Back to the Index 👆

Now that we have completed all of the needed files, lets review everything is in the right place and ready to go.

Files
Links to repos, and proper folder and naming structure for reference.

/styles/variables.css
/styles/globals.css
/styles/theme.util.module.css

/components/theme.util.module.jsx

/pages/_app.jsx

SVGs
Incase you haven’t update the button placeholders yet.

const buttonIcon = () => {
 switch ( theme ) {
 case 'dark' : return ( <svg width="24" height="24" viewBox="0 0 24 24"><path d="M0 12c0 6.627 5.373 12 12 12s12-5.373 12-12-5.373-12-12-12-12 5.373-12 12zm2 0c0-5.514 4.486-10 10-10v20c-5.514 0-10-4.486-10-10z"/></svg> )
 case 'unicorn' : return ( <svg width="24" height="24" viewBox="0 0 24 24"><path d="M4.823 21.933l2.734-1.171-3.241-8.847-1.561 4.372 2.068 5.646zm-2.594-4.174l-2.229 6.241 3.903-1.672-1.674-4.569zm6.248 2.609l2.934-1.258-3.482-9.141-2.215-1.969-.872 2.443 3.635 9.925zm7.523-3.224l-6.453-5.736 2.785 7.308 3.668-1.572zm-.826-5.003l2.201-1.445c.23-.152.295-.462.143-.693-.152-.232-.463-.295-.692-.143l-2.201 1.445c-.231.151-.295.461-.144.692.096.147.256.226.418.226.095 0 .19-.026.275-.082m-2.993-4.312l1.112-2.388c.117-.25.008-.548-.242-.664-.251-.116-.548-.009-.665.242l-1.111 2.388c-.117.25-.008.547.242.664l.211.047c.189 0 .368-.107.453-.289m-2.627.709c1.539-2.963 1.644-5.73.314-8.222-.09-.169-.263-.265-.442-.265-.37 0-.621.398-.44.736 1.166 2.184 1.058 4.637-.32 7.29-.127.245-.031.547.214.674.073.038.152.057.23.057.18 0 .355-.099.444-.27m6.505 6.095c2.017-1.434 4.463-1.64 7.272-.613.327.119.672-.123.672-.47 0-.203-.125-.395-.328-.47-3.136-1.147-5.894-.9-8.196.738-.224.16-.277.472-.117.698.098.136.251.209.407.209.101 0 .202-.03.29-.092m3.757-6.757l-1.697.014.938 1.415-.511 1.618 1.635-.455 1.381.986.073-1.696 1.365-1.009-1.591-.592-.538-1.61-1.055 1.329zm-7.307 3.624c.276-.009.492-.24.483-.517-.056-1.627.36-1.937 1.377-2.051 1.689-.191 1.785-1.312 1.842-1.982.053-.637.071-.851.773-.903.63-.046 1.331-.16 1.76-.659.461-.538.466-1.358.402-2.164-.021-.276-.266-.478-.537-.459-.275.021-.481.262-.459.537.062.787.011 1.23-.165 1.434-.149.174-.48.271-1.074.314-1.553.114-1.644 1.179-1.697 1.816-.057.668-.082.973-.956 1.071-2.075.234-2.315 1.619-2.266 3.08.01.27.231.483.5.483h.017m7.842-8.675c0 1.006.818 1.824 1.825 1.824 1.006 0 1.824-.818 1.824-1.824 0-1.007-.818-1.825-1.824-1.825-1.007 0-1.825.818-1.825 1.825m-6.623-2.841c1.104 0 2 .897 2 2 0 1.104-.896 2-2 2-1.103 0-2-.896-2-2 0-1.103.897-2 2-2"/></svg> )
 case 'light' : return ( <svg width="24" height="24" viewBox="0 0 24 24"><path d="M12 0c-6.627 0-12 5.373-12 12s5.373 12 12 12 12-5.373 12-12-5.373-12-12-12zm4.95 5.636l1.414 1.414-2.195 2.195c-.372-.562-.853-1.042-1.414-1.414l2.195-2.195zm-5.95-1.636h2v3.101c-.323-.066-.657-.101-1-.101s-.677.035-1 .101v-3.101zm-3.95 1.636l2.195 2.195c-.561.372-1.042.853-1.414 1.415l-2.195-2.196 1.414-1.414zm-3.05 5.364h3.101c-.066.323-.101.657-.101 1s.035.677.101 1h-3.101v-2zm3.05 7.364l-1.414-1.414 2.195-2.195c.372.562.853 1.042 1.414 1.414l-2.195 2.195zm5.95 1.636h-2v-3.101c.323.066.657.101 1 .101s.677-.035 1-.101v3.101zm-1-5c-1.657 0-3-1.343-3-3s1.343-3 3-3 3 1.343 3 3-1.343 3-3 3zm4.95 3.364l-2.195-2.195c.562-.372 1.042-.853 1.414-1.414l2.195 2.195-1.414 1.414zm3.05-5.364h-3.101c.066-.323.101-.657.101-1s-.035-.677-.101-1h3.101v2z"/></svg> )
 }
 }

GitHub repo
Just incase you want to go fork yourself.

Turn on the development mode preview

Go into your CLI and enter npx next dev and it will start the dev environment which you can preview at localhost:3000 in your browser.

Deploy a live website to Vercel for free! 🚀🥳

Good guy Vercel will let you create a hobbyist account to play around with (and host) for free. To be honest its been pretty awesome so far and am in the process of building my new personal website on their platform.

https://nextjs.org/learn/basics/deploying-nextjs-app/github

Check out the footer! 👇

Back to the Index 👆

These instructions are taken from the course linked below, with our customized project replacing their base project.

Setup

First, let’s make sure that your development environment is ready.

• If you don’t have Node.js installed, install it from here. You’ll need Node.js version 10.13 or later.
• You’ll be using your own text editor and terminal app for this tutorial.

📑 Learn: If you are on Windows, we recommend downloading Git for Windows and use Git Bash that comes with it, which supports the UNIX-specific commands in this tutorial. Windows Subsystem for Linux (WSL) is another option.

Install this Dark Mode Next.js app

To create this Next.js app, open your terminal, cd into the directory you’d like to create the app in, and run the following command:

npx create-next-app@latest nextjs-dark-mode --use-npm --example "https://github.com/atlamors/nextjs-dark-mode"

Run the development server

You now have a new directory called nextjs-dark-mode. Let’s cd into it:

cd nextjs-dark-mode

Then, run the following command:

npx run dev

This starts your Next.js app’s “development server” on port 3000.

Let’s check to see if it’s working. Open http://localhost:3000 from your browser.

Continue learning Next.js 🚀🥳

This tutorial is built on Vercel’s Learn Next.js free mini-course. I highly recommend continuing on with their course if you want to learn more about Next.js.

Thank you for reading my first article and tutorial!

I would be happy to answer any questions I can, even happier to recieve feedback and advice on how to make this better! If you find any bugs or sections I missed in this tutorial that do not allow you to complete it — let me know and I’ll fix it right away!

Thanks for stopping by!

Back to the Index 👆