mui · siriwatknp · Oct 10, 2025 · Oct 10, 2025 · Oct 10, 2025 · Oct 13, 2025
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -333,6 +333,9 @@ jobs:
       - run:
           name: Validate type declarations
           command: pnpm validate-declarations
+      - run:
+          name: Run tests that depend on built packages
+          command: pnpm -r run release:test
       - run:
           name: Analyze exported typescript
           command: pnpm test:attw

diff --git a/docs/data/material/guides/typescript/typescript.md b/docs/data/material/guides/typescript/typescript.md
@@ -66,3 +66,48 @@
   // your custom styles go here
 }) as typeof Button;
 ```
+
+## Performance optimizations
+
+When building a custom theme, Material UI provides automatic autocompletion and type checking for all tokens and components.
+However, this comes at the cost of some performance overhead because TypeScript has to instantiate types for all components and their variants. This can lead to slower compilation times, especially in large codebase with intensive theme customization.
+
+Starting from v7.4.0, Material UI offers an optimized path that significantly reduces the type instantiation overhead.
+This path mirrors the exports from `@mui/material/styles` without the automatic inclusion of all component types.
+
+Follow the steps below to enable the optimized path in your project:
+
+1. Update all of the imports in your codebase from.
+
+```diff
+-'@mui/material/styles';
++'@mui/material/stylesOptimized';
+```
+
+:::warning
+The optimization will not take effect if there is a single import from the `@mui/material/styles`.
+:::
+
+2. Use module augmentation to explicitly include the component types to the theme.
+
+```ts
+import { createTheme } from '@mui/material/stylesOptimized';
+
+import { ButtonTheme } from '@mui/material/Button';
+import { TextFieldTheme } from '@mui/material/TextField';
+
+declare module '@mui/material/stylesOptimized' {
+  interface ThemeComponents extends ButtonTheme, TextFieldTheme {}
+}
+
+const theme = createTheme({
+  components: {
+    MuiButton: {
+      // type-safe and autocompletion enabled
+    },
+    MuiTextField: {
+      // type-safe and autocompletion enabled
+    },
+  },
+});
+```
diff --git a/packages/mui-codemod/README.md b/packages/mui-codemod/README.md
@@ -2156,6 +2156,19 @@ npx @mui/codemod@latest deprecations/typography-props <path>
 
 ### v7.0.0
 
+#### `styles-optimized`
+
+```bash
+npx @mui/codemod@latest v7.0.0/styles-optimized <path>
+```
+
+Replace the import of `@mui/material/styles` with `@mui/material/stylesOptimized` to optimize the TypeScript instantiation for theme components.
+
+```diff
+- import { createTheme } from '@mui/material/styles';
++ import { createTheme } from '@mui/material/stylesOptimized';
+```
+
 #### `theme-color-functions`
 
 ```bash

diff --git a/packages/mui-codemod/src/v7.0.0/styles-optimized/actual.js b/packages/mui-codemod/src/v7.0.0/styles-optimized/actual.js
@@ -0,0 +1,11 @@
+import { createTheme } from '@mui/material/styles';
+
+// declare module '@mui/material/styles' {
+//   interface Theme {
+//     custom: {
+//       color: string;
+//     };
+//   }
+// }
+
+createTheme();
diff --git a/packages/mui-codemod/src/v7.0.0/styles-optimized/expected.js b/packages/mui-codemod/src/v7.0.0/styles-optimized/expected.js
@@ -0,0 +1,11 @@
+import { createTheme } from '@mui/material/stylesOptimized';
+
+// declare module '@mui/material/stylesOptimized' {
+//   interface Theme {
+//     custom: {
+//       color: string;
+//     };
+//   }
+// }
+
+createTheme();
diff --git a/packages/mui-codemod/src/v7.0.0/styles-optimized/index.js b/packages/mui-codemod/src/v7.0.0/styles-optimized/index.js
@@ -0,0 +1 @@
+export { default } from './styles-optimized';
diff --git a/packages/mui-codemod/src/v7.0.0/styles-optimized/styles-optimized.js b/packages/mui-codemod/src/v7.0.0/styles-optimized/styles-optimized.js
@@ -0,0 +1,30 @@
+/**
+ * @param {import('jscodeshift').FileInfo} file
+ * @param {import('jscodeshift').API} api
+ */
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+
+  const printOptions = {
+    quote: 'single',
+  };
+
+  root
+    .find(j.ImportDeclaration)
+    .filter((path) => path.node.source.value === '@mui/material/styles')
+    .forEach((path) => {
+      path.node.source.value = '@mui/material/stylesOptimized';
+    });
+
+  return root
+    .toSource(printOptions)
+    .replace(
+      /declare module "@mui\/material\/styles"/g,
+      'declare module "@mui/material/stylesOptimized"',
+    )
+    .replace(
+      /declare module '@mui\/material\/styles'/g,
+      "declare module '@mui/material/stylesOptimized'",
+    );
+}
diff --git a/packages/mui-codemod/src/v7.0.0/styles-optimized/styles-optimized.test.js b/packages/mui-codemod/src/v7.0.0/styles-optimized/styles-optimized.test.js
@@ -0,0 +1,43 @@
+import path from 'path';
+import { expect } from 'chai';
+import jscodeshift from 'jscodeshift';
+import transform from './index';
+import readFile from '../../util/readFile';
+
+function read(fileName) {
+  return readFile(path.join(__dirname, fileName));
+}
+
+describe('@mui/codemod', () => {
+  describe('v7.0.0', () => {
+    describe('styles-optimized', () => {
+      it('transforms as needed', () => {
+        const actual = transform(
+          {
+            source: read('./actual.js'),
+            path: require.resolve('./actual.js'),
+          },
+          { jscodeshift },
+          {},
+        );
+
+        const expected = read('./expected.js');
+        expect(actual).to.equal(expected, 'The transformed version should be correct');
+      });
+
+      it('should be idempotent', () => {
+        const actual = transform(
+          {
+            source: read('./expected.js'),
+            path: require.resolve('./expected.js'),
+          },
+          { jscodeshift },
+          {},
+        );
+
+        const expected = read('./expected.js');
+        expect(actual).to.equal(expected, 'The transformed version should be correct');
+      });
+    });
+  });
+});
diff --git a/packages/mui-lab/src/Masonry/Masonry.d.ts b/packages/mui-lab/src/Masonry/Masonry.d.ts
@@ -1,7 +1,7 @@
 import { ResponsiveStyleValue, SxProps } from '@mui/system';
 import { OverridableComponent, OverrideProps } from '@mui/material/OverridableComponent';
-import { Theme } from '@mui/material/styles';
-import { MasonryClasses } from './masonryClasses';
+import { Theme, CreateThemeComponent } from '@mui/material/stylesOptimized';
+import { MasonryClasses, MasonryClassKey } from './masonryClasses';
 
 export interface MasonryOwnProps {
   /**
@@ -69,4 +69,6 @@ export type MasonryProps<
   AdditionalProps = {},
 > = OverrideProps<MasonryTypeMap<AdditionalProps, RootComponent>, RootComponent>;
 
+export type MasonryTheme = CreateThemeComponent<MasonryClassKey, MasonryProps>;
+
 export default Masonry;
diff --git a/packages/mui-lab/src/TabPanel/TabPanel.d.ts b/packages/mui-lab/src/TabPanel/TabPanel.d.ts
@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { InternalStandardProps as StandardProps } from '@mui/material/internal';
-import { Theme } from '@mui/material/styles';
+import { CreateThemeComponent, Theme } from '@mui/material/stylesOptimized';
 import { SxProps } from '@mui/system';
-import { TabPanelClasses } from './tabPanelClasses';
+import { TabPanelClasses, TabPanelClassKey } from './tabPanelClasses';
 
 export interface TabPanelProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>> {
   /**
@@ -29,6 +29,8 @@ export interface TabPanelProps extends StandardProps<React.HTMLAttributes<HTMLDi
   keepMounted?: boolean;
 }
 
+export type TabPanelTheme = CreateThemeComponent<TabPanelClassKey, TabPanelProps>;
+
 /**
  *
  * Demos:

diff --git a/packages/mui-material/src/Accordion/Accordion.d.ts b/packages/mui-material/src/Accordion/Accordion.d.ts
@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { TransitionProps } from '../transitions/transition';
-import { AccordionClasses } from './accordionClasses';
+import { AccordionClasses, AccordionClassKey } from './accordionClasses';
 import { OverridableComponent, OverrideProps } from '../OverridableComponent';
 import { ExtendPaperTypeMap, PaperProps } from '../Paper/Paper';
 import { CreateSlotsAndSlotProps, SlotComponentProps, SlotProps } from '../utils/types';
@@ -157,4 +157,8 @@ export type AccordionProps<
 
 export interface AccordionOwnerState extends AccordionProps {}
 
+export type AccordionTheme = {
+  MuiAccordion?: CreateThemeComponent<AccordionClassKey, AccordionProps>;
+};
+
 export default Accordion;
diff --git a/packages/mui-material/src/AccordionActions/AccordionActions.d.ts b/packages/mui-material/src/AccordionActions/AccordionActions.d.ts
@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { InternalStandardProps as StandardProps } from '../internal';
-import { AccordionActionsClasses } from './accordionActionsClasses';
+import { AccordionActionsClasses, AccordionActionsClassKey } from './accordionActionsClasses';
 
 export interface AccordionActionsProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>> {
   /**
@@ -35,3 +35,7 @@ export interface AccordionActionsProps extends StandardProps<React.HTMLAttribute
  * - [AccordionActions API](https://mui.com/material-ui/api/accordion-actions/)
  */
 export default function AccordionActions(props: AccordionActionsProps): React.JSX.Element;
+
+export type AccordionActionsTheme = {
+  MuiAccordionActions?: CreateThemeComponent<AccordionActionsClassKey, AccordionActionsProps>;
+};
diff --git a/packages/mui-material/src/AccordionDetails/AccordionDetails.d.ts b/packages/mui-material/src/AccordionDetails/AccordionDetails.d.ts
@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { InternalStandardProps as StandardProps } from '../internal';
-import { AccordionDetailsClasses } from './accordionDetailsClasses';
+import { AccordionDetailsClasses, AccordionDetailsClassKey } from './accordionDetailsClasses';
 
 export interface AccordionDetailsProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>> {
   /**
@@ -30,3 +30,7 @@ export interface AccordionDetailsProps extends StandardProps<React.HTMLAttribute
  * - [AccordionDetails API](https://mui.com/material-ui/api/accordion-details/)
  */
 export default function AccordionDetails(props: AccordionDetailsProps): React.JSX.Element;
+
+export type AccordionDetailsTheme = {
+  MuiAccordionDetails?: CreateThemeComponent<AccordionDetailsClassKey, AccordionDetailsProps>;
+};
diff --git a/packages/mui-material/src/AccordionSummary/AccordionSummary.d.ts b/packages/mui-material/src/AccordionSummary/AccordionSummary.d.ts
@@ -3,8 +3,8 @@ import { SxProps } from '@mui/system';
 import { ButtonBaseProps, ExtendButtonBase, ExtendButtonBaseTypeMap } from '../ButtonBase';
 import { OverrideProps } from '../OverridableComponent';
 import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
-import { Theme } from '../styles';
-import { AccordionSummaryClasses } from './accordionSummaryClasses';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
+import { AccordionSummaryClasses, AccordionSummaryClassKey } from './accordionSummaryClasses';
 
 export interface AccordionSummarySlots {
   /**
@@ -108,4 +108,8 @@ export type AccordionSummaryProps<
   component?: React.ElementType;
 };
 
+export type AccordionSummaryTheme = {
+  MuiAccordionSummary?: CreateThemeComponent<AccordionSummaryClassKey, AccordionSummaryProps>;
+};
+
 export default AccordionSummary;
diff --git a/packages/mui-material/src/Alert/Alert.d.ts b/packages/mui-material/src/Alert/Alert.d.ts
@@ -2,11 +2,11 @@ import * as React from 'react';
 import { OverridableStringUnion } from '@mui/types';
 import { SxProps } from '@mui/system';
 import { SvgIconProps } from '../SvgIcon';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { InternalStandardProps as StandardProps } from '../internal';
 import { IconButtonProps } from '../IconButton';
 import { PaperProps } from '../Paper';
-import { AlertClasses } from './alertClasses';
+import { AlertClasses, AlertClassKey } from './alertClasses';
 import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
 
 export type AlertColor = 'success' | 'info' | 'warning' | 'error';
@@ -203,3 +203,7 @@ export interface AlertOwnerState extends AlertProps {}
  * - inherits [Paper API](https://mui.com/material-ui/api/paper/)
  */
 export default function Alert(props: AlertProps): React.JSX.Element;
+
+export type AlertTheme = {
+  MuiAlert?: CreateThemeComponent<AlertClassKey, AlertProps>;
+};
diff --git a/packages/mui-material/src/AlertTitle/AlertTitle.d.ts b/packages/mui-material/src/AlertTitle/AlertTitle.d.ts
@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { TypographyProps } from '../Typography';
-import { AlertTitleClasses } from './alertTitleClasses';
+import { AlertTitleClasses, AlertTitleClassKey } from './alertTitleClasses';
 
 export interface AlertTitleProps extends TypographyProps<'div'> {
   /**
@@ -31,3 +31,7 @@ export interface AlertTitleProps extends TypographyProps<'div'> {
  * - inherits [Typography API](https://mui.com/material-ui/api/typography/)
  */
 export default function AlertTitle(props: AlertTitleProps): React.JSX.Element;
+
+export type AlertTitleTheme = {
+  MuiAlertTitle?: CreateThemeComponent<AlertTitleClassKey, AlertTitleProps>;
+};
diff --git a/packages/mui-material/src/AppBar/AppBar.d.ts b/packages/mui-material/src/AppBar/AppBar.d.ts
@@ -2,8 +2,8 @@ import * as React from 'react';
 import { SxProps } from '@mui/system';
 import { OverridableStringUnion } from '@mui/types';
 import { OverridableComponent, OverrideProps } from '../OverridableComponent';
-import { PropTypes, Theme } from '../styles';
-import { AppBarClasses } from './appBarClasses';
+import { CreateThemeComponent, PropTypes, Theme } from '../stylesOptimized';
+import { AppBarClasses, AppBarClassKey } from './appBarClasses';
 import { ExtendPaperTypeMap } from '../Paper/Paper';
 
 export interface AppBarPropsColorOverrides {}
@@ -84,4 +84,8 @@ export type AppBarProps<
   component?: React.ElementType;
 };
 
+export type AppBarTheme = {
+  MuiAppBar?: CreateThemeComponent<AppBarClassKey, AppBarProps>;
+};
+
 export default AppBar;
diff --git a/packages/mui-material/src/Autocomplete/Autocomplete.d.ts b/packages/mui-material/src/Autocomplete/Autocomplete.d.ts
@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
 import { OverridableStringUnion } from '@mui/types';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { InternalStandardProps as StandardProps } from '../internal';
 import { IconButtonProps } from '../IconButton';
 import { ChipProps, ChipTypeMap } from '../Chip';
@@ -17,7 +17,7 @@ import useAutocomplete, {
   UseAutocompleteProps,
   AutocompleteFreeSoloValueMapping,
 } from '../useAutocomplete';
-import { AutocompleteClasses } from './autocompleteClasses';
+import { AutocompleteClasses, AutocompleteClassKey } from './autocompleteClasses';
 import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
 
 export interface AutocompletePaperSlotPropsOverrides {}
@@ -421,3 +421,10 @@ export default function Autocomplete<
 >(
   props: AutocompleteProps<Value, Multiple, DisableClearable, FreeSolo, ChipComponent>,
 ): React.JSX.Element;
+
+export type AutocompleteTheme = {
+  MuiAutocomplete?: CreateThemeComponent<
+    AutocompleteClassKey,
+    AutocompleteProps<any, any, any, any>
+  >;
+};