Incorrect Theme type in sx prop when using css vars and custom color scheme

[Xhale1]

Steps to reproduce

Steps:

1. View this example: https://stackblitz.com/edit/vitejs-vite-oemrsrwy?file=src%2Ftheme.ts

Current behavior

When defining a custom color scheme, in this case superDark, there is a type error in App.tsx but not theme.ts

Error in App.tsx

// Error ❌: `Argument of type '"superDark"' is not assignable to parameter of type '"light" | "dark"'.(2345)`
theme.applyStyles('superDark', {
   backgroundColor: '#000',
}),
// ...

No error in theme.ts

// ...
MuiCard: {
  styleOverrides: {
    root: ({ theme }) => ({
      // No error ✅: Types are happy!
      ...theme.applyStyles('superDark', {
        backgroundColor: '#000',
      }),
    }),
  },
},
// ...

Expected behavior

Using typescript module augmentation should enable creating custom color schemes that can be used in the sx prop in components without type errors.

Context

I'm trying to create new color schemes beyond just light and dark.

Your environment

npx @mui/envinfo

  System:
    OS: Linux 5.0 undefined
  Binaries:
    Node: 20.19.1 - /usr/local/bin/node
    npm: 10.8.2 - /usr/local/bin/npm
    pnpm: 8.15.6 - /usr/local/bin/pnpm
  Browsers:
    Chrome: Not Found
    Firefox: Not Found
  npmPackages:
    @emotion/react: ^11.14.0 => 11.14.0 
    @emotion/styled: ^11.14.1 => 11.14.1 
    @mui/core-downloads-tracker:  7.3.4 
    @mui/material: ^7.3.4 => 7.3.4 
    @mui/private-theming:  7.3.3 
    @mui/styled-engine:  7.3.3 
    @mui/system:  7.3.3 
    @mui/types:  7.4.7 
    @mui/utils:  7.3.3 
    @types/react: ^19.2.2 => 19.2.2 
    react: ^19.2.0 => 19.2.0 
    react-dom: ^19.2.0 => 19.2.0 
    typescript: ~5.9.3 => 5.9.3

Search keywords: ColorSchemeOverrides, cssvars typescript

[siriwatknp]

PR Welcome. Here is the fix:

diff --git a/packages/mui-material/src/styles/createThemeNoVars.d.ts b/packages/mui-material/src/styles/createThemeNoVars.d.ts
index e7a1cf61da..a41e1bf798 100644
--- a/packages/mui-material/src/styles/createThemeNoVars.d.ts
+++ b/packages/mui-material/src/styles/createThemeNoVars.d.ts
@@ -4,6 +4,7 @@ import {
   SxProps,
   CSSObject,
   SxConfig,
+  ApplyStyles,
 } from '@mui/system';
 import { Mixins, MixinsOptions } from './createMixins';
 import { Palette, PaletteOptions } from './createPalette';
@@ -18,6 +19,7 @@ import {
   ColorSystemOptions,
   Shape,
   ShapeOptions,
+  SupportedColorScheme,
 } from './createThemeFoundation';
 
 /**
@@ -61,6 +63,7 @@ export interface BaseTheme extends SystemTheme {
   typography: TypographyVariants;
   zIndex: ZIndex;
   unstable_strictMode?: boolean;
+  applyStyles: ApplyStyles<SupportedColorScheme>;
 }
 
 // shut off automatic exporting for the `BaseTheme` above
@@ -69,7 +72,6 @@ export {};
 type CssVarsProperties = CssThemeVariables extends { enabled: true }
   ? Pick<
       CssVarsTheme,
-      | 'applyStyles'
       | 'colorSchemes'
       | 'colorSchemeSelector'
       | 'rootSelector'

[namanguptagit]

Hi @siriwatknp 👋

I’d like to work on this issue and open a PR for the fix you outlined.

The root cause seems to be that applyStyles is missing from the BaseTheme definition in createThemeNoVars.d.ts, which prevents custom color schemes (added via module augmentation) from being recognized outside of theme.ts.

Here’s the planned change:

+ import { ApplyStyles } from '@mui/system';
+ import { SupportedColorScheme } from './createThemeFoundation';

export interface BaseTheme extends SystemTheme {
  ...
+  applyStyles: ApplyStyles<SupportedColorScheme>;
}

This ensures that theme.applyStyles('superDark') works correctly in all files without TypeScript errors.

I’ll implement this patch, test it locally with a minimal reproduction, and then open a PR referencing this issue.

Let me know if there are any additional checks or test cases you’d like included. 👍

[siriwatknp]

Feel free to submit a PR, thanks

[github-actions[bot]]

This issue has been closed. If you have a similar problem but not exactly the same, please open a new issue. Now, if you have additional information related to this issue or things that could help future readers, feel free to leave a comment.