New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →

nextjs-darkmode

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

nextjs-darkmode

Unleash the Power of React Server Components! Use dark/light mode on your site with confidence, without losing any advantages of React Server Components

0.2.0

Source

npm

Version published: 10 months ago

Maintainers: 1

Created: 10 months ago

Source

Nextjs Darkmode

npm bundle size

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.

Motivation

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.

Features

✅ 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
✅ No cookies when not using the corresponding ServerTarget
✅ 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.

Getting Started

Installation

$ pnpm add nextjs-darkmode

$ npm install nextjs-darkmode

$ yarn add nextjs-darkmode

Import Styles

Import styles globally or within layout component.

/* globals.css */
@import "nextjs-darkmode/css";

// layout.tsx
import "nextjs-darkmode/css";

Lite Version

For a lighter version, use nextjs-darkmode-lite:

$ pnpm add nextjs-darkmode-lite

$ npm install nextjs-darkmode-lite

$ yarn add nextjs-darkmode-lite

You need r18gs as a peer-dependency.

Usage

Please explore examples and packages/shared-ui for more working examples. (updates coming soon...)

SPA (e.g., Vite, CRA) and Next.js pages directory (No server components)

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 vite or any other build tool, find a similar root component, e.g., <App /> in CRA and vite.

With Next.js `app` router (Server Components)

Update app/layout.jsx to add Core and ServerTarget to avoid flash of un-themed content:

// app/layout.jsx
import { Core } from "nextjs-darkmode"; // for better tree-shaking
import { ServerTarget } from "nextjs-darkmode/server";

export default function Layout({ children }) {
  return (
    <html lang="en">
      <head />
      <body>
        <ServerTarget />
        <Core />
        {children}
      </body>
    </html>
  );
}

Switch

An elegant color switch to toggle color schemes:

<Switch />

HTML & CSS

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 or ServerTarget element:

:root {
  --background: white;
  --foreground: black;
}

.dark {
  --background: black;
  --foreground: white;
}

/* or */

[data-rm="dark"] {...}

When using ServerTarget, use the CSS general sibling combinator (~):

.selector,
.selector *,
.selector ~ *,
.selector ~ * * {
  --th-variable: value;
}

Using the data-attributes

data-rm -> Resolved Mode

data-m -> User's preference

data-sm -> System preference

Content Security Policy

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" />

Images

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" />;
}

useMode

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;
}

Force per page mode

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>;
}

With Styled Components and any CSS-in-JS

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} />
    </>
  );
}

With Tailwind

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">

Performance

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.

Contributing

We welcome contributions! Check out the Contributing Guide for more details.

🤩 Don't forget to star this repo!

Explore hands-on courses to get started with Turborepo:

Repo Stats

License

MPL-2.0

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

Keywords

FAQs

What is nextjs-darkmode?

Is nextjs-darkmode well maintained?

Package last updated on 13 Jun 2024

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.

Install

nextjs-darkmode

Nextjs Darkmode .css-11gvwjj{object-fit:cover;display:inline;}

Motivation

Features

Getting Started

Installation

Import Styles

Lite Version

Usage

SPA (e.g., Vite, CRA) and Next.js pages directory (No server components)

With Next.js app router (Server Components)

Switch

HTML & CSS

Using the data-attributes

Content Security Policy

Images

useMode

Force per page mode

With Styled Components and any CSS-in-JS

With Tailwind

Performance

Contributing

🤩 Don't forget to star this repo!

License

Keywords

Related posts

NVD Concedes Inability to Keep Pace with Surging CVE Disclosures in 2025

Obfuscation 101: Unmasking the Tricks Behind Malicious Code

Nextjs Darkmode

With Next.js `app` router (Server Components)