[ThemeProvider] Support setting default mode (#43951)

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

@@ -132,6 +132,20 @@ To instantly switch between color schemes with no transition, apply the `disable
 </ThemeProvider>
 ```
 
+## Setting the default mode
+
+When `colorSchemes` is provided, the default mode is `system`, which means the app uses the system preference when users first visit the site.
+
+To set a different default mode, pass the `defaultMode` prop to the ThemeProvider component:
+
+```js
+<ThemeProvider theme={theme} defaultMode="dark">
+```
+
+:::info
+The `defaultMode` value can be `'light'`, `'dark'`, or `'system'`.
+:::
+
 ## Styling in dark mode
 
 Use the `theme.applyStyles` utility to apply styles for a specific mode.

packages/mui-material/src/styles/ThemeProvider.test.tsx

@@ -95,5 +95,18 @@ describe('ThemeProvider', () => {
 
       expect(getByTestId('mode-switcher')).to.have.property('value', 'dark');
     });
+
+    it('allows default mode to be changed', () => {
+      const theme = createTheme({
+        colorSchemes: { dark: true },
+      });
+      const { getByTestId } = render(
+        <ThemeProvider theme={theme} defaultMode="dark">
+          <ModeSwitcher />
+        </ThemeProvider>,
+      );
+
+      expect(getByTestId('mode-switcher')).to.have.property('value', 'dark');
+    });
   });
 });

packages/mui-material/src/styles/ThemeProvider.tsx

@@ -36,6 +36,12 @@ export interface ThemeProviderProps<Theme = DefaultTheme> extends ThemeProviderC
    * @default document
    */
   documentNode?: Document | null;
+  /**
+   * The default mode when the local storage has no mode yet,
+   * requires the theme to have `colorSchemes` with light and dark.
+   * @default 'system'
+   */
+  defaultMode?: 'light' | 'dark' | 'system';
   /**
    * The window that attaches the 'storage' event listener
    * @default window

packages/mui-system/src/cssVars/createCssVarsProvider.d.ts

@@ -54,6 +54,12 @@ export interface CreateCssVarsProviderResult<
             colorSchemeSelector?: 'media' | 'class' | 'data' | string;
           }
         >;
+        /**
+         * The default mode when the storage is empty,
+         * require the theme to have `colorSchemes` with light and dark.
+         * @default 'system'
+         */
+        defaultMode?: 'light' | 'dark' | 'system';
         /**
          * The document used to perform `disableTransitionOnChange` feature
          * @default document

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

@@ -60,6 +60,7 @@ export default function createCssVarsProvider(options) {
       colorSchemeNode = typeof document === 'undefined' ? undefined : document.documentElement,
       disableNestedContext = false,
       disableStyleSheetGeneration = false,
+      defaultMode: initialMode = 'system',
     } = props;
     const hasMounted = React.useRef(false);
     const upperTheme = muiUseTheme();
@@ -92,7 +93,7 @@ export default function createCssVarsProvider(options) {
       typeof defaultColorScheme === 'string' ? defaultColorScheme : defaultColorScheme.dark;
     const defaultMode =
       colorSchemes[defaultLightColorScheme] && colorSchemes[defaultDarkColorScheme]
-        ? 'system'
+        ? initialMode
         : colorSchemes[restThemeProp.defaultColorScheme]?.palette?.mode ||
           restThemeProp.palette?.mode;
 
@@ -299,6 +300,11 @@ export default function createCssVarsProvider(options) {
      * localStorage key used to store `colorScheme`
      */
     colorSchemeStorageKey: PropTypes.string,
+    /**
+     * The default mode when the storage is empty,
+     * require the theme to have `colorSchemes` with light and dark.
+     */
+    defaultMode: PropTypes.string,
     /**
      * If `true`, the provider creates its own context and generate stylesheet as if it is a root `CssVarsProvider`.
      */