[system] Warn when calling setMode without configuring colorSchemeSelector

packages/mui-material/src/styles/ThemeProviderWithVars.test.js

@@ -1,8 +1,15 @@
 import * as React from 'react';
 import { expect } from 'chai';
-import { createRenderer, screen } from '@mui/internal-test-utils';
+import { createRenderer, screen, fireEvent } from '@mui/internal-test-utils';
 import Box from '@mui/material/Box';
-import { CssVarsProvider, extendTheme, useTheme } from '@mui/material/styles';
+import {
+  CssVarsProvider,
+  extendTheme,
+  useTheme,
+  ThemeProvider,
+  createTheme,
+  useColorScheme,
+} from '@mui/material/styles';
 
 describe('[Material UI] ThemeProviderWithVars', () => {
   let originalMatchmedia;
@@ -360,4 +367,45 @@ describe('[Material UI] ThemeProviderWithVars', () => {
       borderBottomRightRadius: '16px',
     });
   });
+
+  it('warns when using `setMode` without configuring `colorSchemeSelector`', () => {
+    function Test() {
+      const { setMode } = useColorScheme();
+      return <button onClick={() => setMode('dark')}>Dark</button>;
+    }
+    render(
+      <ThemeProvider
+        theme={createTheme({ cssVariables: true, colorSchemes: { light: true, dark: true } })}
+      >
+        <Test />
+      </ThemeProvider>,
+    );
+
+    expect(() => {
+      fireEvent.click(screen.getByText('Dark'));
+    }).toErrorDev([
+      'MUI: The `setMode` function has no effect if `colorSchemeSelector` is `media` (`media` is the default value).\nTo toggle the mode manually, please configure `colorSchemeSelector` to use a class or data attribute.\nTo learn more, visit https://mui.com/material-ui/customization/css-theme-variables/configuration/#toggling-dark-mode-manually',
+    ]);
+  });
+
+  it('do not warn when using `setMode` with `colorSchemeSelector` that is not `media`', () => {
+    function Test() {
+      const { setMode } = useColorScheme();
+      return <button onClick={() => setMode('dark')}>Dark</button>;
+    }
+    render(
+      <ThemeProvider
+        theme={createTheme({
+          cssVariables: { colorSchemeSelector: 'class' },
+          colorSchemes: { light: true, dark: true },
+        })}
+      >
+        <Test />
+      </ThemeProvider>,
+    );
+
+    expect(() => {
+      fireEvent.click(screen.getByText('Dark'));
+    }).not.toErrorDev();
+  });
 });

packages/mui-system/src/cssVars/createCssVarsProvider.js

@@ -242,7 +242,21 @@ export default function createCssVarsProvider(options) {
         lightColorScheme,
         mode,
         setColorScheme,
-        setMode,
+        setMode:
+          process.env.NODE_ENV === 'production'
+            ? setMode
+            : (newMode) => {
+                if (theme.colorSchemeSelector === 'media') {
+                  console.error(
+                    [
+                      'MUI: The `setMode` function has no effect if `colorSchemeSelector` is `media` (`media` is the default value).',
+                      'To toggle the mode manually, please configure `colorSchemeSelector` to use a class or data attribute.',
+                      'To learn more, visit https://mui.com/material-ui/customization/css-theme-variables/configuration/#toggling-dark-mode-manually',
+                    ].join('\n'),
+                  );
+                }
+                setMode(newMode);
+              },
         systemMode,
       }),
       [
@@ -254,6 +268,7 @@ export default function createCssVarsProvider(options) {
         setColorScheme,
         setMode,
         systemMode,
+        theme.colorSchemeSelector,
       ],
     );