add theme.applyStyles doc

mui · Feb 6, 2024 · d873af8 · d873af8
1 parent 90f655a
commit d873af8
Show file tree

Hide file tree

Showing 2 changed files with 76 additions and 3 deletions.
diff --git a/docs/data/material/customization/dark-mode/dark-mode.md b/docs/data/material/customization/dark-mode/dark-mode.md
@@ -146,3 +146,76 @@ function App() {
   );
 }
 ```
+
+## Styling in dark mode
+
+The `theme.applyStyles()` function, introduced in `@mui/material` [v5.15.7](https://github.com/mui/material-ui/releases/tag/v5.15.7), lets you apply styles for a specific mode.
+
+We recommend using this function in favor of the `theme.palette.mode` check, as it's more readable and lets you smoothly adopt new features in the future.
+
+### Usage
+
+With the `**styled**` function:
+
+```jsx
+import { styled } from '@mui/material/styles';
+
+const MyComponent = styled('div')(
+  ({ theme }) => ({
+    color: '#fff',
+    backgroundColor: theme.palette.primary.main,
+    '&:hover': {
+      boxShadow: theme.shadows[3],
+      backgroundColor: theme.palette.primary.dark,
+    },
+  }),
+  ({ theme }) =>
+    theme.applyStyles('dark', {
+      backgroundColor: theme.palette.secondary.main,
+    }),
+);
+```
+
+With the `**sx**` prop:
+
+```jsx
+import Button from '@mui/material/Button';
+
+<Button
+  sx={[
+    (theme) => ({
+      color: '#fff',
+      backgroundColor: theme.palette.primary.main,
+      '&:hover': {
+        boxShadow: theme.shadows[3],
+        backgroundColor: theme.palette.primary.dark,
+      },
+    }),
+    (theme) =>
+      theme.applyStyles('dark', {
+        backgroundColor: theme.palette.secondary.main,
+      }),
+  ]}
+>
+  Submit
+</Button>;
+```
+
+### Codemod
+
+We provide a codemod to migrate your codebase from using `theme.palette.mode` to use `theme.applyStyles()`.
+
+```sh
+npx @mui/codemod@latest deprecations/mode-to-apply-styles path/to/your/files
+```
+
+### API
+
+`theme.applyStyles(mode, styles) => CSSObject`
+
+Apply styles for a specific mode.
+
+#### Arguments
+
+- `mode` (`'light' | 'dark'`) - The mode for which the styles should be applied.
+- `styles` (`CSSObject`) - An object which contains the styles to be applied for the specified mode.
diff --git a/docs/data/material/experimental-api/css-theme-variables/customization.md b/docs/data/material/experimental-api/css-theme-variables/customization.md
@@ -227,7 +227,7 @@ const theme = extendTheme({ cssVarPrefix: '' });
 
 ## Custom styles per mode
 
-To customize the style without creating new tokens, you can use the `theme.getColorSchemeSelector` utility:
+Starting from `@mui/material` [v5.15.7](https://github.com/mui/material-ui/releases/tag/v5.15.7), we recommend using `theme.applyStyles` utility to apply styles for a specific mode:
 
 ```js
 const Button = styled('button')(({ theme }) => ({
@@ -239,14 +239,14 @@ const Button = styled('button')(({ theme }) => ({
   },
 
   // in dark mode.
-  [theme.getColorSchemeSelector('dark')]: {
+  ...theme.applyStyles('dark', {
     backgroundColor: theme.vars.palette.primary.dark,
     color: theme.vars.palette.primary.main,
     '&:hover': {
       color: '#fff',
       backgroundColor: theme.vars.palette.primary.dark,
     },
-  },
+  }),
 }));
 ```