Skip to content
+

Dark mode

Learn about the different methods for applying dark mode to a Joy UI app.

Set as default

To set dark mode as the default for your app, add defaultMode: 'dark' to your <CssVarsProvider> wrapper component:

Dark mode
Default

For server-side applications, check out the framework setup in the section below and provide the same value to the InitColorSchemeScript component:

<InitColorSchemeScript defaultMode="dark" />

Matching device's preference

Use defaultMode: 'system' to set your app's default mode to match the user's chosen preference on their device.

import { CssVarsProvider } from '@mui/joy/styles';

<CssVarsProvider defaultMode="system">...</CssVarsProvider>;

For server-side applications, check out the framework setup in the section below and provide the same value to the InitColorSchemeScript component:

<InitColorSchemeScript defaultMode="system" />

Identify the system mode

Use the useColorScheme React hook to check if the user's preference is in light or dark mode:

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.
}
Calculating…
Press Enter to start editing

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 Button component that calls setMode from the useColorSchemes() hook to handle the mode toggling.

import { useColorScheme } from '@mui/joy/styles';
import Button from '@mui/joy/Button';

function ModeToggle() {
  const { mode, setMode } = useColorScheme();
  return (
    <Button
      variant="outlined"
      color="neutral"
      onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}
    >
      {mode === 'dark' ? 'Turn light' : 'Turn dark'}
    </Button>
  );
}

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.

 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 <Button variant="outlined" color="neutral" sx={{ width: 120 }} />;
+  }

   return (
     <Button
       variant="outlined"
       color="neutral"
       onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}
     >
       {mode === 'dark' ? 'Turn light' : 'Turn dark'}
     </Button>
   );
 };

Avoiding screen flickering

To prevent the UI from flickering, add the <InitColorSchemeScript /> component before the <CssVarsProvider /> component:

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 file in order to prevent flickering:

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 (
    <html lang="en" suppressHydrationWarning={true}>
      <body>
        <InitColorSchemeScript />
        <CssVarsProvider>
          <CssBaseline />
          {props.children}
        </CssVarsProvider>
      </body>
    </html>
  );
}

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 file:

import Document, { Html, Head, Main, NextScript } from 'next/document';
import InitColorSchemeScript from '@mui/joy/InitColorSchemeScript';

export default class MyDocument extends Document {
  render() {
    return (
      <Html data-color-scheme="light">
        <Head>...</Head>
        <body>
          <InitColorSchemeScript />
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}