We are launching version 3.0 with minor API changes and major performance improvement and fixes. We have tried our best to ensure minimum changes to existing APIs. For most users we recommend using nthul package.
🤟 👉 Unleash the Power of React Server Components
This project is inspired by next-themes
. next-themes
is an awesome package, however, it requires wrapping everything in a client side provider. And thus, it takes away all the benefits of Server Components.
react18-themes
removes this limitation and enables you to unleash the full power of React 18 Server Components. In addition, more features are coming up soon... Stay tuned!
import from react18-themes/client/component
)appDir
useTheme
hooklocalStorage
is used as default storage. No cookies
by default. Use storage="cookies" for smooth initial rendering of server components.Check out the live example.
$ pnpm add react18-themes
or
$ npm install react18-themes
or
$ yarn add react18-themes
$ pnpm add react18-themes-lite
or
$ npm install react18-themes-lite
or
$ yarn add react18-themes-lite
You need r18gs as a peer-dependency
The best way is to add a Custom App
to use by modifying _app
as follows:
Adding dark mode support takes 2 lines of code:
import { ThemeSwitcher } from "react18-themes";
function MyApp({ Component, pageProps }) {
return (
<>
<ThemeSwitcher forcedTheme={Component.theme} />
<Component {...pageProps} />
</>
);
}
export default MyApp;
⚡🎉Boom! Just a couple of lines and your dark mode is ready!
Check out examples for advanced usage.
app
router (Server Components)If your app is mostly serving static content, you do not want the overhead of SSR. Use
NextJsSSGThemeSwitcher
in this case. When using this approach, you need to use CSS general sibling Combinator (~) to make sure your themed CSS is properly applied. See (HTML & CSS)[#html--css].
Update your app/layout.jsx
to add ThemeSwitcher
from react18-themes
, and NextJsSSGThemeSwitcher
from react18-themes/server
. NextJsSSGThemeSwitcher
is required to avoid flash of un-themed content on reload.
// app/layout.jsx
import { ThemeSwitcher } from "react18-themes";
import { NextJsSSGThemeSwitcher } from "react18-themes/server/nextjs";
export default function Layout({ children }) {
return (
<html lang="en">
<head />
<body>
/** use NextJsSSGThemeSwitcher as first element inside body */
<NextJsSSGThemeSwitcher />
<ThemeSwitcher />
{children}
</body>
</html>
);
}
Woohoo! You just added multiple theme modes and you can also use Server Component! Isn't that awesome!
If your app is serving dynamic content and you want to utilize SSR, continue using
ServerSideWrapper
component to replacehtml
tag inlayout.tsx
file.
Update your app/layout.jsx
to add ThemeSwitcher
and ServerSideWrapper
from react18-themes
. ServerSideWrapper
is required to avoid flash of un-themed content on reload.
// app/layout.jsx
import { ThemeSwitcher } from "react18-themes";
import { ServerSideWrapper } from "react18-themes/server/nextjs";
export default function Layout({ children }) {
return (
<ServerSideWrapper tag="html" lang="en">
<head />
<body>
<ThemeSwitcher />
{children}
</body>
</ServerSideWrapper>
);
}
Woohoo! You just added dark mode and you can also use Server Component! Isn't that awesome!
That's it, your Next.js app fully supports dark mode, including System preference with prefers-color-scheme
. The theme is also immediately synced between tabs. By default, react18-themes modifies the data-theme
attribute on the html
element, which you can easily use to style your app:
:root {
/* Your default theme */
--background: white;
--foreground: black;
}
[data-theme="dark"] {
--background: black;
--foreground: white;
}
// v2 onwards when using NextJsSSGThemeSwitcher, we need to use CSS Combinators
[data-theme="dark"] ~ * {
--background: black;
--foreground: white;
}
In case your components need to know the current theme and be able to change it. The useTheme
hook provides theme information:
import { useTheme } from "react18-themes";
const ThemeChanger = () => {
const { theme, setTheme } = useTheme();
return (
<div>
The current theme is: {theme}
<button onClick={() => setTheme("light")}>Light Mode</button>
<button onClick={() => setTheme("dark")}>Dark Mode</button>
</div>
);
};
import { ForceTheme } from "react18-themes";
function MyPage() {
return (
<>
<ForceTheme theme={"my-theme"} />
...
</>
);
}
export default MyPage;
For pages router, you have 2 options. One is the same as the app router and the other option which is compatible with next-themes
is to add theme
to your page component as follows.
function MyPage() {
return <>...</>;
}
MyPage.theme = "my-theme";
export default MyPage;
In a similar way, you can also force color scheme.
Forcing color scheme will apply your defaultDark or defaultLight theme, configurable via hooks.
Find changelog here CHANGELOG.md
For server side syncing, we need to use cookies and headers. This means that this component and its children can not be static. They will be rendered server side for each request. Thus, we are avoiding the wrapper. Now, only the NextJsSSGThemeSwitcher
will be rendered server side for each request and rest of your app can be server statically.
Take care of the following while migrating to v2
.
Next.js
app router or server components other than updating cookies policy if needed.cookies
in place of localStorage
. (You might want to update cookies policy accordingly.)localStorage
. You can change it to cookies
or sassionStorage
by passing storage
prop to <ThemeSwitcher />
component.NextJsSSGThemeSwitcher
in addition to ServerSideWrapper
for Next.js
. You no longer need to use a wrapper component which broke static generation and forced SSR.app
router (Server Components)defaultDarkTheme
is renamed to darkTheme
setDefaultDarkTheme
is renamed to setDarkTheme
defaultLightTheme
is renamed to lightTheme
setDefaultLightTheme
is renamed to setLightTheme
Want handson course for getting started with Turborepo? Check out React and Next.js with TypeScript
Licensed as MIT open source.
with 💖 by Mayank Kumar Chaudhari