diff --git a/README.md b/README.md deleted file mode 100644 index a2fcd5ef..00000000 --- a/README.md +++ /dev/null @@ -1,558 +0,0 @@ -# next-themes ![next-themes minzip package size](https://img.shields.io/bundlephobia/minzip/next-themes) [![Version](https://img.shields.io/npm/v/next-themes.svg?colorB=green)](https://www.npmjs.com/package/next-themes) - -An abstraction for themes in your React app. - -- ✅ Perfect dark mode in 2 lines of code -- ✅ System setting with prefers-color-scheme -- ✅ Themed browser UI with color-scheme -- ✅ Support for Next.js 13 `appDir` -- ✅ No flash on load (both SSR and SSG) -- ✅ Sync theme across tabs and windows -- ✅ Disable flashing when changing themes -- ✅ Force pages to specific themes -- ✅ Class or data attribute selector -- ✅ `useTheme` hook - -Check out the [Live Example](https://next-themes-example.vercel.app/) to try it for yourself. - -## Install - -```bash -$ npm install next-themes -# or -$ yarn add next-themes -``` - -## Use - -### With pages/ - -You'll need a [Custom `App`](https://nextjs.org/docs/advanced-features/custom-app) to use next-themes. The simplest `_app` looks like this: - -```jsx -// pages/_app.js - -function MyApp({ Component, pageProps }) { - return -} - -export default MyApp -``` - -Adding dark mode support takes 2 lines of code: - -```jsx -import { ThemeProvider } from 'next-themes' - -function MyApp({ Component, pageProps }) { - return ( - - - - ) -} - -export default MyApp -``` - -### With app/ - -You'll need to update your `app/layout.jsx` to use next-themes. The simplest `layout` looks like this: - -```jsx -// app/layout.jsx - -export default function Layout({ children }) { - return ( - - - {children} - - ) -} -``` - -Adding dark mode support still only takes a few lines of code. Start by creating a new [providers component](https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns#using-context-providers) in its own file: - -```jsx -// app/providers.jsx - -'use client' - -import { ThemeProvider } from 'next-themes' - -export function Providers({ children }) { - return {children} -} -``` - -Then add the `` component to your layout _inside_ of the ``. - -```jsx -// app/layout.jsx - -import { Providers } from './providers' - -export default function Layout({ children }) { - return ( - - - - {children} - - - ) -} -``` - -> **Note!** If you do not add [suppressHydrationWarning](https://reactjs.org/docs/dom-elements.html#suppresshydrationwarning:~:text=It%20only%20works%20one%20level%20deep) to your `` you will get warnings because `next-themes` updates that element. This property only applies one level deep, so it won't block hydration warnings on other elements. - -### HTML & CSS - -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, next-themes modifies the `data-theme` attribute on the `html` element, which you can easily use to style your app: - -```css -:root { - /* Your default theme */ - --background: white; - --foreground: black; -} - -[data-theme='dark'] { - --background: black; - --foreground: white; -} -``` - -> **Note!** If you set the attribute of your Theme Provider to class for Tailwind next-themes will modify the `class` attribute on the `html` element. See [With Tailwind](#with-tailwind). - -### useTheme - -Your UI will need to know the current theme and be able to change it. The `useTheme` hook provides theme information: - -```jsx -import { useTheme } from 'next-themes' - -const ThemeChanger = () => { - const { theme, setTheme } = useTheme() - - return ( -
- The current theme is: {theme} - - -
- ) -} -``` - -> **Warning!** The above code is hydration _unsafe_ and will throw a hydration mismatch warning when rendering with SSG or SSR. This is because we cannot know the `theme` on the server, so it will always be `undefined` until mounted on the client. -> -> You should delay rendering any theme toggling UI until mounted on the client. See the [example](#avoid-hydration-mismatch). - -## API - -Let's dig into the details. - -### ThemeProvider - -All your theme configuration is passed to ThemeProvider. - -- `storageKey = 'theme'`: Key used to store theme setting in localStorage -- `defaultTheme = 'system'`: Default theme name (for v0.0.12 and lower the default was `light`). If `enableSystem` is false, the default theme is `light` -- `forcedTheme`: Forced theme name for the current page (does not modify saved theme settings) -- `enableSystem = true`: Whether to switch between `dark` and `light` based on `prefers-color-scheme` -- `enableColorScheme = true`: Whether to indicate to browsers which color scheme is used (dark or light) for built-in UI like inputs and buttons -- `disableTransitionOnChange = false`: Optionally disable all CSS transitions when switching themes ([example](#disable-transitions-on-theme-change)) -- `themes = ['light', 'dark']`: List of theme names -- `attribute = 'data-theme'`: HTML attribute modified based on the active theme - - accepts `class` and `data-*` (meaning any data attribute, `data-mode`, `data-color`, etc.) ([example](#class-instead-of-data-attribute)) -- `value`: Optional mapping of theme name to attribute value - - value is an `object` where key is the theme name and value is the attribute value ([example](#differing-dom-attribute-and-theme-name)) -- `nonce`: Optional nonce passed to the injected `script` tag, used to allow-list the next-themes script in your CSP - -### useTheme - -useTheme takes no parameters, but returns: - -- `theme`: Active theme name -- `setTheme(name)`: Function to update the theme -- `forcedTheme`: Forced page theme or falsy. If `forcedTheme` is set, you should disable any theme switching UI -- `resolvedTheme`: If `enableSystem` is true and the active theme is "system", this returns whether the system preference resolved to "dark" or "light". Otherwise, identical to `theme` -- `systemTheme`: If `enableSystem` is true, represents the System theme preference ("dark" or "light"), regardless what the active theme is -- `themes`: The list of themes passed to `ThemeProvider` (with "system" appended, if `enableSystem` is true) - -Not too bad, right? Let's see how to use these properties with examples: - -## Examples - -The [Live Example](https://next-themes-example.vercel.app/) shows next-themes in action, with dark, light, system themes and pages with forced themes. - -### Use System preference by default - -For versions above v0.0.12, the `defaultTheme` is automatically set to "system", so to use System preference you can simply use: - -```jsx - -``` - -### Ignore System preference - -If you don't want a System theme, disable it via `enableSystem`: - -```jsx - -``` - -### Class instead of data attribute - -If your Next.js app uses a class to style the page based on the theme, change the attribute prop to `class`: - -```jsx - -``` - -Now, setting the theme to "dark" will set `class="dark"` on the `html` element. - -### Force page to a theme - -Let's say your cool new marketing page is dark mode only. The page should always use the dark theme, and changing the theme should have no effect. To force a theme on your Next.js pages, simply set a variable on the page component: - -```js -// pages/awesome-page.js - -const Page = () => { ... } -Page.theme = 'dark' -export default Page -``` - -In your `_app`, read the variable and pass it to ThemeProvider: - -```jsx -function MyApp({ Component, pageProps }) { - return ( - - - - ) -} -``` - -Done! Your page is always dark theme (regardless of user preference), and calling `setTheme` from `useTheme` is now a no-op. However, you should make sure to disable any of your UI that would normally change the theme: - -```js -const { forcedTheme } = useTheme() - -// Theme is forced, we shouldn't allow user to change the theme -const disabled = !!forcedTheme -``` - -### Disable transitions on theme change - -I wrote about [this technique here](https://paco.sh/blog/disable-theme-transitions). We can forcefully disable all CSS transitions before the theme is changed, and re-enable them immediately afterwards. This ensures your UI with different transition durations won't feel inconsistent when changing the theme. - -To enable this behavior, pass the `disableTransitionOnChange` prop: - -```jsx - -``` - -### Differing DOM attribute and theme name - -The name of the active theme is used as both the localStorage value and the value of the DOM attribute. If the theme name is "pink", localStorage will contain `theme=pink` and the DOM will be `data-theme="pink"`. You **cannot** modify the localStorage value, but you **can** modify the DOM value. - -If we want the DOM to instead render `data-theme="my-pink-theme"` when the theme is "pink", pass the `value` prop: - -```jsx - -``` - -Done! To be extra clear, this affects only the DOM. Here's how all the values will look: - -```js -const { theme } = useTheme() -// => "pink" - -localStorage.getItem('theme') -// => "pink" - -document.documentElement.getAttribute('data-theme') -// => "my-pink-theme" -``` - -### More than light and dark mode - -next-themes is designed to support any number of themes! Simply pass a list of themes: - -```jsx - -``` - -> **Note!** When you pass `themes`, the default set of themes ("light" and "dark") are overridden. Make sure you include those if you still want your light and dark themes: - -```jsx - -``` - -### Without CSS variables - -This library does not rely on your theme styling using CSS variables. You can hard-code the values in your CSS, and everything will work as expected (without any flashing): - -```css -html, -body { - color: #000; - background: #fff; -} - -[data-theme='dark'], -[data-theme='dark'] body { - color: #fff; - background: #000; -} -``` - -### With Styled Components and any CSS-in-JS - -Next Themes is completely CSS independent, it will work with any library. For example, with Styled Components you just need to `createGlobalStyle` in your custom App: - -```jsx -// pages/_app.js -import { createGlobalStyle } from 'styled-components' -import { ThemeProvider } from 'next-themes' - -// Your themeing variables -const GlobalStyle = createGlobalStyle` - :root { - --fg: #000; - --bg: #fff; - } - - [data-theme="dark"] { - --fg: #fff; - --bg: #000; - } -` - -function MyApp({ Component, pageProps }) { - return ( - <> - - - - - - ) -} -``` - -### Avoid Hydration Mismatch - -Because we cannot know the `theme` on the server, many of the values returned from `useTheme` will be `undefined` until mounted on the client. This means if you try to render UI based on the current theme before mounting on the client, you will see a hydration mismatch error. - -The following code sample is **unsafe**: - -```jsx -import { useTheme } from 'next-themes' - -// Do NOT use this! It will throw a hydration mismatch error. -const ThemeSwitch = () => { - const { theme, setTheme } = useTheme() - - return ( - - ) -} - -export default ThemeSwitch -``` - -To fix this, make sure you only render UI that uses the current theme when the page is mounted on the client: - -```jsx -import { useState, useEffect } from 'react' -import { useTheme } from 'next-themes' - -const ThemeSwitch = () => { - const [mounted, setMounted] = useState(false) - const { theme, setTheme } = useTheme() - - // useEffect only runs on the client, so now we can safely show the UI - useEffect(() => { - setMounted(true) - }, []) - - if (!mounted) { - return null - } - - return ( - - ) -} - -export default ThemeSwitch -``` - -To avoid [Layout Shift](https://web.dev/cls/), consider rendering a skeleton/placeholder until mounted on the client side. - -#### Images - -Showing different images based on the current theme also suffers from the hydration mismatch problem. With [`next/image`](https://nextjs.org/docs/basic-features/image-optimization) you can use an empty image until the theme is resolved: - -```jsx -import Image from 'next/image' -import { useTheme } from 'next-themes' - -function ThemedImage() { - const { resolvedTheme } = useTheme() - let src - - switch (resolvedTheme) { - case 'light': - src = '/light.png' - break - case 'dark': - src = '/dark.png' - break - default: - src = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7' - break - } - - return -} - -export default ThemedImage -``` - -#### CSS - -You can also use CSS to hide or show content based on the current theme. To avoid the hydration mismatch, you'll need to render _both_ versions of the UI, with CSS hiding the unused version. For example: - -```jsx -function ThemedImage() { - return ( - <> - {/* When the theme is dark, hide this div */} -
- -
- - {/* When the theme is light, hide this div */} -
- -
- - ) -} - -export default ThemedImage -``` - -```css -[data-theme='dark'] [data-hide-on-theme='dark'], -[data-theme='light'] [data-hide-on-theme='light'] { - display: none; -} -``` - -### With Tailwind - -[Visit the live example](https://next-themes-tailwind.vercel.app) • [View the example source code](https://github.com/pacocoursey/next-themes/tree/master/examples/tailwind) - -> NOTE! Tailwind only supports dark mode in version >2. - -In your `tailwind.config.js`, set the dark mode property to class: - -```js -// tailwind.config.js -module.exports = { - darkMode: 'class' -} -``` - -Set the attribute for your Theme Provider to class: - -```jsx -// pages/_app.js - -``` - -If you're using the `value` prop to specify different attribute values, make sure your dark theme explicitly uses the "dark" value, as required by Tailwind. - -That's it! Now you can use dark-mode specific classes: - -```jsx -

-``` - -## Discussion - -### The Flash - -ThemeProvider automatically injects a script into `next/head` to update the `html` element with the correct attributes before the rest of your page loads. This means the page will not flash under any circumstances, including forced themes, system theme, multiple themes, and incognito. No `noflash.js` required. - -## FAQ - ---- - -**Why is my page still flashing?** - -In Next.js dev mode, the page may still flash. When you build your app in production mode, there will be no flashing. - ---- - -**Why do I get server/client mismatch error?** - -When using `useTheme`, you will use see a hydration mismatch error when rendering UI that relies on the current theme. This is because many of the values returned by `useTheme` are undefined on the server, since we can't read `localStorage` until mounting on the client. See the [example](#avoid-hydration-mismatch) for how to fix this error. - ---- - -**Do I need to use CSS variables with this library?** - -Nope. See the [example](#without-css-variables). - ---- - -**Can I set the class or data attribute on the body or another element?** - -Nope. If you have a good reason for supporting this feature, please open an issue. - ---- - -**Can I use this package with Gatsby or CRA?** - -Yes, starting from the 0.3.0 version. - ---- - -**Is the injected script minified?** - -Yes, using Terser. - ---- - -**Why is `resolvedTheme` necessary?** - -When supporting the System theme preference, you want to make sure that's reflected in your UI. This means your buttons, selects, dropdowns, or whatever you use to indicate the current theme should say "System" when the System theme preference is active. - -If we didn't distinguish between `theme` and `resolvedTheme`, the UI would show "Dark" or "Light", when it should really be "System". - -`resolvedTheme` is then useful for modifying behavior or styles at runtime: - -```jsx -const { resolvedTheme } = useTheme() - -
-``` - -If we didn't have `resolvedTheme` and only used `theme`, you'd lose information about the state of your UI (you would only know the theme is "system", and not what it resolved to). diff --git a/README.md b/README.md new file mode 120000 index 00000000..c7895fc4 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +./next-themes/README.md \ No newline at end of file diff --git a/license.md b/license.md deleted file mode 100644 index 76228ccc..00000000 --- a/license.md +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2022 Paco Coursey - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/license.md b/license.md new file mode 120000 index 00000000..b59f83ed --- /dev/null +++ b/license.md @@ -0,0 +1 @@ +./next-themes/license.md \ No newline at end of file diff --git a/next-themes/README.md b/next-themes/README.md new file mode 100644 index 00000000..a2fcd5ef --- /dev/null +++ b/next-themes/README.md @@ -0,0 +1,558 @@ +# next-themes ![next-themes minzip package size](https://img.shields.io/bundlephobia/minzip/next-themes) [![Version](https://img.shields.io/npm/v/next-themes.svg?colorB=green)](https://www.npmjs.com/package/next-themes) + +An abstraction for themes in your React app. + +- ✅ Perfect dark mode in 2 lines of code +- ✅ System setting with prefers-color-scheme +- ✅ Themed browser UI with color-scheme +- ✅ Support for Next.js 13 `appDir` +- ✅ No flash on load (both SSR and SSG) +- ✅ Sync theme across tabs and windows +- ✅ Disable flashing when changing themes +- ✅ Force pages to specific themes +- ✅ Class or data attribute selector +- ✅ `useTheme` hook + +Check out the [Live Example](https://next-themes-example.vercel.app/) to try it for yourself. + +## Install + +```bash +$ npm install next-themes +# or +$ yarn add next-themes +``` + +## Use + +### With pages/ + +You'll need a [Custom `App`](https://nextjs.org/docs/advanced-features/custom-app) to use next-themes. The simplest `_app` looks like this: + +```jsx +// pages/_app.js + +function MyApp({ Component, pageProps }) { + return +} + +export default MyApp +``` + +Adding dark mode support takes 2 lines of code: + +```jsx +import { ThemeProvider } from 'next-themes' + +function MyApp({ Component, pageProps }) { + return ( + + + + ) +} + +export default MyApp +``` + +### With app/ + +You'll need to update your `app/layout.jsx` to use next-themes. The simplest `layout` looks like this: + +```jsx +// app/layout.jsx + +export default function Layout({ children }) { + return ( + + + {children} + + ) +} +``` + +Adding dark mode support still only takes a few lines of code. Start by creating a new [providers component](https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns#using-context-providers) in its own file: + +```jsx +// app/providers.jsx + +'use client' + +import { ThemeProvider } from 'next-themes' + +export function Providers({ children }) { + return {children} +} +``` + +Then add the `` component to your layout _inside_ of the ``. + +```jsx +// app/layout.jsx + +import { Providers } from './providers' + +export default function Layout({ children }) { + return ( + + + + {children} + + + ) +} +``` + +> **Note!** If you do not add [suppressHydrationWarning](https://reactjs.org/docs/dom-elements.html#suppresshydrationwarning:~:text=It%20only%20works%20one%20level%20deep) to your `` you will get warnings because `next-themes` updates that element. This property only applies one level deep, so it won't block hydration warnings on other elements. + +### HTML & CSS + +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, next-themes modifies the `data-theme` attribute on the `html` element, which you can easily use to style your app: + +```css +:root { + /* Your default theme */ + --background: white; + --foreground: black; +} + +[data-theme='dark'] { + --background: black; + --foreground: white; +} +``` + +> **Note!** If you set the attribute of your Theme Provider to class for Tailwind next-themes will modify the `class` attribute on the `html` element. See [With Tailwind](#with-tailwind). + +### useTheme + +Your UI will need to know the current theme and be able to change it. The `useTheme` hook provides theme information: + +```jsx +import { useTheme } from 'next-themes' + +const ThemeChanger = () => { + const { theme, setTheme } = useTheme() + + return ( +
+ The current theme is: {theme} + + +
+ ) +} +``` + +> **Warning!** The above code is hydration _unsafe_ and will throw a hydration mismatch warning when rendering with SSG or SSR. This is because we cannot know the `theme` on the server, so it will always be `undefined` until mounted on the client. +> +> You should delay rendering any theme toggling UI until mounted on the client. See the [example](#avoid-hydration-mismatch). + +## API + +Let's dig into the details. + +### ThemeProvider + +All your theme configuration is passed to ThemeProvider. + +- `storageKey = 'theme'`: Key used to store theme setting in localStorage +- `defaultTheme = 'system'`: Default theme name (for v0.0.12 and lower the default was `light`). If `enableSystem` is false, the default theme is `light` +- `forcedTheme`: Forced theme name for the current page (does not modify saved theme settings) +- `enableSystem = true`: Whether to switch between `dark` and `light` based on `prefers-color-scheme` +- `enableColorScheme = true`: Whether to indicate to browsers which color scheme is used (dark or light) for built-in UI like inputs and buttons +- `disableTransitionOnChange = false`: Optionally disable all CSS transitions when switching themes ([example](#disable-transitions-on-theme-change)) +- `themes = ['light', 'dark']`: List of theme names +- `attribute = 'data-theme'`: HTML attribute modified based on the active theme + - accepts `class` and `data-*` (meaning any data attribute, `data-mode`, `data-color`, etc.) ([example](#class-instead-of-data-attribute)) +- `value`: Optional mapping of theme name to attribute value + - value is an `object` where key is the theme name and value is the attribute value ([example](#differing-dom-attribute-and-theme-name)) +- `nonce`: Optional nonce passed to the injected `script` tag, used to allow-list the next-themes script in your CSP + +### useTheme + +useTheme takes no parameters, but returns: + +- `theme`: Active theme name +- `setTheme(name)`: Function to update the theme +- `forcedTheme`: Forced page theme or falsy. If `forcedTheme` is set, you should disable any theme switching UI +- `resolvedTheme`: If `enableSystem` is true and the active theme is "system", this returns whether the system preference resolved to "dark" or "light". Otherwise, identical to `theme` +- `systemTheme`: If `enableSystem` is true, represents the System theme preference ("dark" or "light"), regardless what the active theme is +- `themes`: The list of themes passed to `ThemeProvider` (with "system" appended, if `enableSystem` is true) + +Not too bad, right? Let's see how to use these properties with examples: + +## Examples + +The [Live Example](https://next-themes-example.vercel.app/) shows next-themes in action, with dark, light, system themes and pages with forced themes. + +### Use System preference by default + +For versions above v0.0.12, the `defaultTheme` is automatically set to "system", so to use System preference you can simply use: + +```jsx + +``` + +### Ignore System preference + +If you don't want a System theme, disable it via `enableSystem`: + +```jsx + +``` + +### Class instead of data attribute + +If your Next.js app uses a class to style the page based on the theme, change the attribute prop to `class`: + +```jsx + +``` + +Now, setting the theme to "dark" will set `class="dark"` on the `html` element. + +### Force page to a theme + +Let's say your cool new marketing page is dark mode only. The page should always use the dark theme, and changing the theme should have no effect. To force a theme on your Next.js pages, simply set a variable on the page component: + +```js +// pages/awesome-page.js + +const Page = () => { ... } +Page.theme = 'dark' +export default Page +``` + +In your `_app`, read the variable and pass it to ThemeProvider: + +```jsx +function MyApp({ Component, pageProps }) { + return ( + + + + ) +} +``` + +Done! Your page is always dark theme (regardless of user preference), and calling `setTheme` from `useTheme` is now a no-op. However, you should make sure to disable any of your UI that would normally change the theme: + +```js +const { forcedTheme } = useTheme() + +// Theme is forced, we shouldn't allow user to change the theme +const disabled = !!forcedTheme +``` + +### Disable transitions on theme change + +I wrote about [this technique here](https://paco.sh/blog/disable-theme-transitions). We can forcefully disable all CSS transitions before the theme is changed, and re-enable them immediately afterwards. This ensures your UI with different transition durations won't feel inconsistent when changing the theme. + +To enable this behavior, pass the `disableTransitionOnChange` prop: + +```jsx + +``` + +### Differing DOM attribute and theme name + +The name of the active theme is used as both the localStorage value and the value of the DOM attribute. If the theme name is "pink", localStorage will contain `theme=pink` and the DOM will be `data-theme="pink"`. You **cannot** modify the localStorage value, but you **can** modify the DOM value. + +If we want the DOM to instead render `data-theme="my-pink-theme"` when the theme is "pink", pass the `value` prop: + +```jsx + +``` + +Done! To be extra clear, this affects only the DOM. Here's how all the values will look: + +```js +const { theme } = useTheme() +// => "pink" + +localStorage.getItem('theme') +// => "pink" + +document.documentElement.getAttribute('data-theme') +// => "my-pink-theme" +``` + +### More than light and dark mode + +next-themes is designed to support any number of themes! Simply pass a list of themes: + +```jsx + +``` + +> **Note!** When you pass `themes`, the default set of themes ("light" and "dark") are overridden. Make sure you include those if you still want your light and dark themes: + +```jsx + +``` + +### Without CSS variables + +This library does not rely on your theme styling using CSS variables. You can hard-code the values in your CSS, and everything will work as expected (without any flashing): + +```css +html, +body { + color: #000; + background: #fff; +} + +[data-theme='dark'], +[data-theme='dark'] body { + color: #fff; + background: #000; +} +``` + +### With Styled Components and any CSS-in-JS + +Next Themes is completely CSS independent, it will work with any library. For example, with Styled Components you just need to `createGlobalStyle` in your custom App: + +```jsx +// pages/_app.js +import { createGlobalStyle } from 'styled-components' +import { ThemeProvider } from 'next-themes' + +// Your themeing variables +const GlobalStyle = createGlobalStyle` + :root { + --fg: #000; + --bg: #fff; + } + + [data-theme="dark"] { + --fg: #fff; + --bg: #000; + } +` + +function MyApp({ Component, pageProps }) { + return ( + <> + + + + + + ) +} +``` + +### Avoid Hydration Mismatch + +Because we cannot know the `theme` on the server, many of the values returned from `useTheme` will be `undefined` until mounted on the client. This means if you try to render UI based on the current theme before mounting on the client, you will see a hydration mismatch error. + +The following code sample is **unsafe**: + +```jsx +import { useTheme } from 'next-themes' + +// Do NOT use this! It will throw a hydration mismatch error. +const ThemeSwitch = () => { + const { theme, setTheme } = useTheme() + + return ( + + ) +} + +export default ThemeSwitch +``` + +To fix this, make sure you only render UI that uses the current theme when the page is mounted on the client: + +```jsx +import { useState, useEffect } from 'react' +import { useTheme } from 'next-themes' + +const ThemeSwitch = () => { + const [mounted, setMounted] = useState(false) + const { theme, setTheme } = useTheme() + + // useEffect only runs on the client, so now we can safely show the UI + useEffect(() => { + setMounted(true) + }, []) + + if (!mounted) { + return null + } + + return ( + + ) +} + +export default ThemeSwitch +``` + +To avoid [Layout Shift](https://web.dev/cls/), consider rendering a skeleton/placeholder until mounted on the client side. + +#### Images + +Showing different images based on the current theme also suffers from the hydration mismatch problem. With [`next/image`](https://nextjs.org/docs/basic-features/image-optimization) you can use an empty image until the theme is resolved: + +```jsx +import Image from 'next/image' +import { useTheme } from 'next-themes' + +function ThemedImage() { + const { resolvedTheme } = useTheme() + let src + + switch (resolvedTheme) { + case 'light': + src = '/light.png' + break + case 'dark': + src = '/dark.png' + break + default: + src = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7' + break + } + + return +} + +export default ThemedImage +``` + +#### CSS + +You can also use CSS to hide or show content based on the current theme. To avoid the hydration mismatch, you'll need to render _both_ versions of the UI, with CSS hiding the unused version. For example: + +```jsx +function ThemedImage() { + return ( + <> + {/* When the theme is dark, hide this div */} +
+ +
+ + {/* When the theme is light, hide this div */} +
+ +
+ + ) +} + +export default ThemedImage +``` + +```css +[data-theme='dark'] [data-hide-on-theme='dark'], +[data-theme='light'] [data-hide-on-theme='light'] { + display: none; +} +``` + +### With Tailwind + +[Visit the live example](https://next-themes-tailwind.vercel.app) • [View the example source code](https://github.com/pacocoursey/next-themes/tree/master/examples/tailwind) + +> NOTE! Tailwind only supports dark mode in version >2. + +In your `tailwind.config.js`, set the dark mode property to class: + +```js +// tailwind.config.js +module.exports = { + darkMode: 'class' +} +``` + +Set the attribute for your Theme Provider to class: + +```jsx +// pages/_app.js + +``` + +If you're using the `value` prop to specify different attribute values, make sure your dark theme explicitly uses the "dark" value, as required by Tailwind. + +That's it! Now you can use dark-mode specific classes: + +```jsx +

+``` + +## Discussion + +### The Flash + +ThemeProvider automatically injects a script into `next/head` to update the `html` element with the correct attributes before the rest of your page loads. This means the page will not flash under any circumstances, including forced themes, system theme, multiple themes, and incognito. No `noflash.js` required. + +## FAQ + +--- + +**Why is my page still flashing?** + +In Next.js dev mode, the page may still flash. When you build your app in production mode, there will be no flashing. + +--- + +**Why do I get server/client mismatch error?** + +When using `useTheme`, you will use see a hydration mismatch error when rendering UI that relies on the current theme. This is because many of the values returned by `useTheme` are undefined on the server, since we can't read `localStorage` until mounting on the client. See the [example](#avoid-hydration-mismatch) for how to fix this error. + +--- + +**Do I need to use CSS variables with this library?** + +Nope. See the [example](#without-css-variables). + +--- + +**Can I set the class or data attribute on the body or another element?** + +Nope. If you have a good reason for supporting this feature, please open an issue. + +--- + +**Can I use this package with Gatsby or CRA?** + +Yes, starting from the 0.3.0 version. + +--- + +**Is the injected script minified?** + +Yes, using Terser. + +--- + +**Why is `resolvedTheme` necessary?** + +When supporting the System theme preference, you want to make sure that's reflected in your UI. This means your buttons, selects, dropdowns, or whatever you use to indicate the current theme should say "System" when the System theme preference is active. + +If we didn't distinguish between `theme` and `resolvedTheme`, the UI would show "Dark" or "Light", when it should really be "System". + +`resolvedTheme` is then useful for modifying behavior or styles at runtime: + +```jsx +const { resolvedTheme } = useTheme() + +
+``` + +If we didn't have `resolvedTheme` and only used `theme`, you'd lose information about the state of your UI (you would only know the theme is "system", and not what it resolved to). diff --git a/next-themes/license.md b/next-themes/license.md new file mode 100644 index 00000000..76228ccc --- /dev/null +++ b/next-themes/license.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2022 Paco Coursey + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE.