Learn about the different methods for applying dark mode to a Joy UI app.
## Media prefers-color-scheme
Create a theme with `colorSchemeSelector: 'media'` to use `@media (prefers-color-scheme)` instead of the default `data-joy-color-scheme` attribute.
```js
import { extendTheme } from '@mui/joy/styles';
const theme = extendTheme({
colorSchemeSelector: 'media',
});
function App() {
return ...;
}
```
## Identify the system mode
Use the `useColorScheme` React hook to check if the user's preference is in light or dark mode:
```js
import { useColorScheme } from '@mui/joy/styles';
function SomeComponent() {
const { mode, systemMode } = useColorScheme();
console.log(mode); // "system"
console.log(systemMode); // "light" | "dark" based on the user's preference.
}
```
{{"demo": "IdentifySystemMode.js"}}
:::warning
The `useColorScheme()` hook only works with components nested inside of ``—otherwise it will throw an error.
:::
## Creating a mode-toggle component
You can create a toggle component to give users the option to select between modes.
In the example below, we're using a `Select` component that calls `setMode` from the `useColorSchemes()` hook to handle the mode switching.
{{"demo": "ModeToggle.js"}}
:::warning
The `useColorScheme()` hook only works with components nested inside of ``—otherwise it will throw an error.
:::
## Server-side rendering notes
### Avoid hydration mismatch
Make sure to render the UI when the page is mounted on the client.
This is because the `mode` will only be available to the client-side (it is `undefined` on the server).
If you try to render your UI based on the server, before mounting on the client, you'll see a hydration mismatch error.
```diff
function ModeToggle() {
const { mode, setMode } = useColorScheme();
const [mounted, setMounted] = React.useState(false);
+ React.useEffect(() => {
+ setMounted(true);
+ }, []);
+
+ if (!mounted) {
+ // to avoid layout shift, render a placeholder button
+ return ;
+ }
return (
);
};
```
### Avoiding screen flickering
To [prevent the UI from flickering](/joy-ui/main-features/dark-mode-optimization/#the-problem-flickering-on-first-load), apply `` before the main application script－it varies across frameworks:
### Next.js Pages Router
To use the Joy UI API with a Next.js project, add the following code to the custom [`pages/_document.js`](https://nextjs.org/docs/pages/building-your-application/routing/custom-document) file:
```jsx
import Document, { Html, Head, Main, NextScript } from 'next/document';
import InitColorSchemeScript from '@mui/joy/InitColorSchemeScript';
export default class MyDocument extends Document {
render() {
return (
...
);
}
}
```
### Next.js App Router
To use the Joy UI API with a Next.js project with the App Router, add the following code to the [root layout](https://nextjs.org/docs/app/api-reference/file-conventions/layout#root-layouts) file in order to prevent flickering:
```jsx title="app/layout.js"
import InitColorSchemeScript from '@mui/joy/InitColorSchemeScript';
import { CssVarsProvider } from '@mui/joy/styles';
import CssBaseline from '@mui/joy/CssBaseline';
export default function RootLayout(props) {
return (
{props.children}
);
}
```