diff --git a/docs/data/material/customization/dark-mode/dark-mode.md b/docs/data/material/customization/dark-mode/dark-mode.md index 86921f703c53d3..eed4715ff98bd4 100644 --- a/docs/data/material/customization/dark-mode/dark-mode.md +++ b/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 ``` +## 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 + +``` + +:::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. diff --git a/packages/mui-material/src/styles/ThemeProvider.test.tsx b/packages/mui-material/src/styles/ThemeProvider.test.tsx index d21e01db663f23..b5828595030b49 100644 --- a/packages/mui-material/src/styles/ThemeProvider.test.tsx +++ b/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( + + + , + ); + + expect(getByTestId('mode-switcher')).to.have.property('value', 'dark'); + }); }); }); diff --git a/packages/mui-material/src/styles/ThemeProvider.tsx b/packages/mui-material/src/styles/ThemeProvider.tsx index cf8775ad32b0e2..ffdab139176ea9 100644 --- a/packages/mui-material/src/styles/ThemeProvider.tsx +++ b/packages/mui-material/src/styles/ThemeProvider.tsx @@ -36,6 +36,12 @@ export interface ThemeProviderProps 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 diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.d.ts b/packages/mui-system/src/cssVars/createCssVarsProvider.d.ts index 542c6f9b016e01..f1d7ba4ddc10a6 100644 --- a/packages/mui-system/src/cssVars/createCssVarsProvider.d.ts +++ b/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 diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.js b/packages/mui-system/src/cssVars/createCssVarsProvider.js index 435d0231618ee7..9b521128ec13ab 100644 --- a/packages/mui-system/src/cssVars/createCssVarsProvider.js +++ b/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`. */