init project

docs/data/joy/customization/dark-mode/IdentifySystemMode.js

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import { CssVarsProvider, useColorScheme, extendTheme } from '@mui/joy/styles';
+import Typography from '@mui/joy/Typography';
+
+const theme = extendTheme({ cssVarPrefix: 'demo' });
+
+function Identifier() {
+  const { systemMode } = useColorScheme();
+  const [mounted, setMounted] = React.useState(false);
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+  if (!mounted) {
+    return (
+      <Typography component="div" sx={{ fontSize: 'lg', opacity: 0 }}>
+        Calculating…
+      </Typography>
+    );
+  }
+  return (
+    <Typography component="div" sx={{ fontSize: 'lg' }}>
+      Your system is in{' '}
+      <Typography
+        variant="outlined"
+        sx={{
+          fontSize: 'md',
+          boxShadow: 'sm',
+          fontFamily: 'code',
+          bgcolor: 'background.level1',
+        }}
+      >
+        {systemMode}
+      </Typography>{' '}
+      mode.
+    </Typography>
+  );
+}
+
+export default function IdentifySystemMode() {
+  return (
+    <CssVarsProvider
+      // The props below are specific to this demo,
+      // you might not need them in your app.
+      //
+      theme={theme}
+      // the local storage key to use.
+      modeStorageKey="demo_identify-system-mode"
+      // set as root provider
+      disableNestedContext
+    >
+      <Identifier />
+    </CssVarsProvider>
+  );
+}

docs/data/joy/customization/dark-mode/IdentifySystemMode.tsx

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import { CssVarsProvider, useColorScheme, extendTheme } from '@mui/joy/styles';
+import Typography from '@mui/joy/Typography';
+
+const theme = extendTheme({ cssVarPrefix: 'demo' });
+
+function Identifier() {
+  const { systemMode } = useColorScheme();
+  const [mounted, setMounted] = React.useState(false);
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+  if (!mounted) {
+    return (
+      <Typography component="div" sx={{ fontSize: 'lg', opacity: 0 }}>
+        Calculating…
+      </Typography>
+    );
+  }
+  return (
+    <Typography component="div" sx={{ fontSize: 'lg' }}>
+      Your system is in{' '}
+      <Typography
+        variant="outlined"
+        sx={{
+          fontSize: 'md',
+          boxShadow: 'sm',
+          fontFamily: 'code',
+          bgcolor: 'background.level1',
+        }}
+      >
+        {systemMode}
+      </Typography>{' '}
+      mode.
+    </Typography>
+  );
+}
+
+export default function IdentifySystemMode() {
+  return (
+    <CssVarsProvider
+      // The props below are specific to this demo,
+      // you might not need them in your app.
+      //
+      theme={theme}
+      // the local storage key to use.
+      modeStorageKey="demo_identify-system-mode"
+      // set as root provider
+      disableNestedContext
+    >
+      <Identifier />
+    </CssVarsProvider>
+  );
+}

docs/data/joy/customization/dark-mode/IdentifySystemMode.tsx.preview

@@ -0,0 +1,12 @@
+<CssVarsProvider
+  // The props below are specific to this demo,
+  // you might not need them in your app.
+  //
+  theme={theme}
+  // the local storage key to use.
+  modeStorageKey="demo_identify-system-mode"
+  // set as root provider
+  disableNestedContext
+>
+  <Identifier />
+</CssVarsProvider>

docs/data/joy/customization/dark-mode/ModeToggle.js

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import { CssVarsProvider, useColorScheme, extendTheme } from '@mui/joy/styles';
+import Select from '@mui/joy/Select';
+import Option from '@mui/joy/Option';
+
+function ModeSwitcher() {
+  const { mode, setMode } = useColorScheme();
+  const [mounted, setMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) {
+    return null;
+  }
+  return (
+    <Select
+      variant="soft"
+      value={mode}
+      onChange={(event, newMode) => {
+        setMode(newMode);
+      }}
+    >
+      <Option value="system">System</Option>
+      <Option value="light">Light</Option>
+      <Option value="dark">Dark</Option>
+    </Select>
+  );
+}
+
+const theme = extendTheme({
+  cssVarPrefix: 'mode-toggle',
+  colorSchemeSelector: '.demo_mode-toggle-%s',
+});
+
+export default function ModeToggle() {
+  return (
+    <CssVarsProvider
+      // the props below are specific to this demo,
+      // you might not need them in your app.
+      //
+      theme={theme}
+      //
+      // the local storage key to use.
+      modeStorageKey="mode-toggle-demo"
+      //
+      // set as root provider
+      disableNestedContext
+    >
+      <ModeSwitcher />
+    </CssVarsProvider>
+  );
+}

docs/data/joy/customization/dark-mode/ModeToggle.tsx

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import { CssVarsProvider, useColorScheme, extendTheme } from '@mui/joy/styles';
+import Select from '@mui/joy/Select';
+import Option from '@mui/joy/Option';
+
+function ModeSwitcher() {
+  const { mode, setMode } = useColorScheme();
+  const [mounted, setMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) {
+    return null;
+  }
+  return (
+    <Select
+      variant="soft"
+      value={mode}
+      onChange={(event, newMode) => {
+        setMode(newMode);
+      }}
+    >
+      <Option value="system">System</Option>
+      <Option value="light">Light</Option>
+      <Option value="dark">Dark</Option>
+    </Select>
+  );
+}
+
+const theme = extendTheme({
+  cssVarPrefix: 'mode-toggle',
+  colorSchemeSelector: '.demo_mode-toggle-%s',
+});
+
+export default function ModeToggle() {
+  return (
+    <CssVarsProvider
+      // the props below are specific to this demo,
+      // you might not need them in your app.
+      //
+      theme={theme}
+      //
+      // the local storage key to use.
+      modeStorageKey="mode-toggle-demo"
+      //
+      // set as root provider
+      disableNestedContext
+    >
+      <ModeSwitcher />
+    </CssVarsProvider>
+  );
+}

docs/data/joy/customization/dark-mode/ModeToggle.tsx.preview

@@ -0,0 +1,14 @@
+<CssVarsProvider
+  // the props below are specific to this demo,
+  // you might not need them in your app.
+  //
+  theme={theme}
+  //
+  // the local storage key to use.
+  modeStorageKey="mode-toggle-demo"
+  //
+  // set as root provider
+  disableNestedContext
+>
+  <ModeSwitcher />
+</CssVarsProvider>

docs/data/joy/customization/dark-mode/dark-mode.md

@@ -0,0 +1,138 @@
+# Dark mode
+
+<p class="description">Learn about the different methods for applying dark mode to a Joy UI app.</p>
+
+## 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 <CssVarsProvider theme={theme}>...</CssVarsProvider>;
+}
+```
+
+## 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 `<CssVarsProvider>`—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 `<CssVarsProvider>`—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 <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](/joy-ui/main-features/dark-mode-optimization/#the-problem-flickering-on-first-load), apply `<InitColorSchemeScript />` 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 (
+      <Html data-color-scheme="light">
+        <Head>...</Head>
+        <body>
+          <InitColorSchemeScript />
+          <Main />
+          <NextScript />
+        </body>
+      </Html>
+    );
+  }
+}
+```
+
+### 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 (
+    <html lang="en" suppressHydrationWarning={true}>
+      <body>
+        <InitColorSchemeScript />
+        <CssVarsProvider>
+          <CssBaseline />
+          {props.children}
+        </CssVarsProvider>
+      </body>
+    </html>
+  );
+}
+```