nextjs-darkmode
Advanced tools
Unleash the Power of React Server Components! Use dark/light mode on your site with confidence, without losing any advantages of React Server Components
Nextjs Darkmode is a versatile library crafted to fully utilize React 18 server components, ensuring a seamless dark mode experience in Next.js applications. Lightweight and efficient, it respects both user preferences and system settings through the prefers-color-scheme media query, and integrates effortlessly with React/Vite, Remix, and Next.js.
The nextjs-themes library was initially created to achieve a similar functionality to next-themes with React Server Components. While effective, it felt bulky for those supporting only dark/light mode. Thus, nextjs-darkmode was developed to offer a minimal footprint while utilizing Next.js Server Components, avoiding any flash of unthemed content, and ensuring theme synchronization with the server.
For migration guide please refer Project Wiki
✅ Simple API to toggle between dark and light modes
✅ Perfect dark mode with just 2 lines of code
✅ Compatible with Tailwind CSS, StyledComponents, emotion, Material UI, ...
✅ Secure by design - we support nonce when you want to apply Content Security Policy
✅ Fully treeshakable (e.g., import from nextjs-darkmode/hooks)
✅ Full TypeScript support
✅ Utilizes React 18 Server components
✅ Compatible with all React 18 build systems/tools/frameworks
✅ System setting with prefers-color-scheme
✅ Supports Next.js 13 & 14 appDir
✅ No flash on load (supports SSG, SSR, ISG, and Server Components)
✅ Sync theme across tabs and windows
✅ Apply custom transitions when changing themes
✅ Manipulate theme via the useMode hook
✅ Comprehensive documentation with Typedoc
Feel free to request new features, discuss, or report bugs.
Please consider starring this repository and sharing it with your friends.
$ pnpm add nextjs-darkmode
or
$ npm install nextjs-darkmode
or
$ yarn add nextjs-darkmode
PLease make sure you set
"moduleResolution"to"Bundler","Node16"or"NodeNext"in your tsconfig file for export field in package.json to work properly. (Ref)[https://stackoverflow.com/a/74462490/23175171]
You may need to import styles from
nextjs-darkmode/dist/index.cssdepending on your bundler configuration.
Import styles globally or within layout component.
/* globals.css */
@import "nextjs-darkmode/css";
// layout.tsx
import "nextjs-darkmode/css";
For a lighter version, use nextjs-darkmode-lite:
$ pnpm add nextjs-darkmode-lite
or
$ npm install nextjs-darkmode-lite
or
$ yarn add nextjs-darkmode-lite
You need
r18gsas a peer-dependency.
Please explore
examplesandpackages/shared-uifor more working examples. (updates coming soon...)
Modify _app to add dark mode support:
import { Core } from "nextjs-darkmode"; // for better tree-shaking
import { Switch } from "nextjs-darkmode/switch";
function MyApp({ Component, pageProps }) {
return (
<>
<Core />
<header>
<Switch />
</header>
<Component {...pageProps} />
</>
);
}
export default MyApp;
⚡🎉Boom! Just a couple of lines and your dark mode is ready, complete with a color switch for user preferences. Check out examples for advanced usage.
For
viteor any other build tool, find a similar root component, e.g.,<App />inCRAandvite.
app routerUpdate app/layout.jsx to add Core component.
// app/layout.jsx
import { Core } from "nextjs-darkmode"; // for better tree-shaking
export default function Layout({ children }) {
return (
<html lang="en">
<head />
<body>
<Core />
{children}
</body>
</html>
);
}
An elegant color switch to toggle color schemes:
<Switch />
Fully support dark mode, including system preference with prefers-color-scheme. The dark/light mode is synced between tabs and modifies the className and data-attributes on the html elemnt.
:root {
--background: white;
--foreground: black;
}
.dark {
--background: black;
--foreground: white;
}
/* or */
[data-rm="dark"] {...}
data-attributes are very helpful when you want to customize styles in a CSS module file (styles.module.css)
data-rm -> Resolved Mode
data-m -> User's preference
data-sm -> System preference
If you are using CSP rules for CSS files, you can pass nonce argument to the Core component. If nonce is not supplied transition styles will not be applied. This may allow patched transitions throught the page in some cases.
<Core nonce={yourNonce} t="transition: all .5s" />
Show different images based on the current theme:
import Image from "next/image";
import { useMode } from "nextjs-darkmode/hooks";
function ThemedImage() {
const { resolvedMode } = useMode();
let src;
switch (resolvedMode) {
case "light":
src = "/light-mode-image.png";
break;
case "dark":
src = "/dark-mode-image.png";
break;
default:
src = "/default-image.png";
break;
}
return <Image src={src} alt="Themed Image" />;
}
The useMode hook provides mode information:
import { useMode } from "nextjs-darkmode";
const ThemeChanger = () => {
const { resolvedMode, setMode } = useMode();
return (
<div>
The current resolved mode is: {resolvedMode}
<button onClick={() => setMode("light")}>Light Mode</button>
<button onClick={() => setMode("dark")}>Dark Mode</button>
</div>
);
};
useMode hook returns the following object:
export interface UseModeInterface {
mode: ColorSchemePreference;
systemMode: ResolvedScheme;
resolvedMode: ResolvedScheme;
setMode: (mode: ColorSchemePreference) => void;
}
Apply appropriate class names and data attributes to force a mode for the page:
export default function Page() {
return <div className="dark ndm-scoped data-rm='dark'">...</div>;
}
Next Themes works with any library. For example, with Styled Components:
// pages/_app.js
import { createGlobalStyle } from "styled-components";
import { Core } from "nextjs-darkmode";
// Your theming variables
const GlobalStyle = createGlobalStyle`
:root {
--fg: #000;
--bg: #fff;
}
[data-rm="dark"] {
--fg: #fff;
--bg: #000;
}
`;
function MyApp({ Component, pageProps }) {
return (
<>
<GlobalStyle />
<Core />
<Component {...pageProps} />
</>
);
}
In tailwind.config.js, set the dark mode property to class:
// tailwind.config.js
module.exports = {
darkMode: "class",
};
Now you can use dark-mode specific classes:
<h1 className="text-black dark:text-white">
nextjs-darkmode is designed to be fully tree-shakable, including only the code you use. For instance, if you only use the useMode hook, the rest of the library's code will be removed during the build process.
We welcome contributions! Check out the Contributing Guide for more details.
Explore hands-on courses to get started with Turborepo:
Feel free to use, modify, and distribute this library under the MPL-2.0 license.
Please consider enrolling in our courses or sponsoring our work.
with 💖 by Mayank Kumar Chaudhari
FAQs
Unleash the Power of React Server Components! Use dark/light mode on your site with confidence, without losing any advantages of React Server Components
The npm package nextjs-darkmode receives a total of 992 weekly downloads. As such, nextjs-darkmode popularity was classified as not popular.
We found that nextjs-darkmode demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PEP 770 proposes adding SBOM support to Python packages to improve transparency and catch hidden non-Python dependencies that security tools often miss.
Security News
Socket CEO Feross Aboukhadijeh discusses open source security challenges, including zero-day attacks and supply chain risks, on the Cyber Security Council podcast.
Security News
Research
Socket researchers uncover how threat actors weaponize Out-of-Band Application Security Testing (OAST) techniques across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.