Theme Composition doesn't work with css variables option

[astjohnpaycor]

Steps to reproduce

Link to live example: https://codesandbox.io/p/sandbox/muithemebug-2cllq4

Steps:

1. Use createTheme function and pass cssVariables option in as true
2. Use createTheme again, with the theme that you just created passed in, with the second parameter being the new arguments that you want to merge into the theme.
3. See error.

Current behavior

The theme is broken because of this error "MUI: vars is a private field used for CSS variables support.
Please use another name." and then cannot be used. This is because when the first one gets created it strips out the "cssVariables" argument and creates the vars key and values. So when you use createTheme again, it thinks that it is using the createThemeNoVars option and there's no way to tell it otherwise, and so complains that you used the reserved vars keyword.

Expected behavior

Per the theme composition instructions that are just below this anchor: https://mui.com/material-ui/customization/theming/#createtheme-options-args-theme

I would expect that I am able to build a theme that is based on the values of the previous theme, while also using css variables. This works as expected when you are not using css variables.

Context

We are trying to use theme composition to set styles that are based on the values being created by the theme, e.g. breakpoints, and we also want to be able to use css variables in our theme.

Your environment

npx @mui/envinfo

  System:
    OS: macOS 15.0
  Binaries:
    Node: 20.15.1 - /opt/homebrew/opt/node@20/bin/node
    npm: 10.7.0 - /opt/homebrew/opt/node@20/bin/npm
    pnpm: Not Found
  Browsers:
    Chrome: 130.0.6723.59
    Edge: 129.0.2792.89
    Safari: 18.0

I primarily use Firefox Developer Edition, but this is not a browser issue.

Search keywords: createTheme cssVariables composition

[siriwatknp]

@mnajdova I am not convinced that this is a bug. It's more a docs improvement because you'd want to set cssVariables: true at the last createTheme for highest performant.

@astjohnpaycor Does the change below work for your use case?

let theme = createTheme({
-  cssVariables: true,
  typography: {
    h1: {
      fontFamily: "Verdana, Arial, sans-serif",
    },
  },
});

theme = createTheme(theme, {
+  cssVariables: true,
  typography: {
    h1: {
      [theme.breakpoints.only("lg")]: {
        fontSize: "2.5rem",
        lineHeight: "106%",
      },
    },
  },
});

[astjohnpaycor]

@siriwatknp No, that doesn't work because the theme has already been created when you use the subsequent `createTheme` calls, so passing in the `cssVariables` property later doesn't do anything. It doesn't go back through and recreate the theme with the css variables. If that is expected behavior, then that would also be a bug, but I don't think it's expected behavior since this does clarify that only the first argument gets processed and that you have to do deep merging if you're trying to fully re-create the theme with all the options: https://mui.com/material-ui/customization/theming/#createtheme-options-args-theme