Documentation for extending theme is wrong. Module Augmentation does not work.

[crtl]

In https://mui.com/customization/theming/#custom-variables the docs tell you to use following example to extend typescript type but it is not working:

declare module '@mui/material/styles' {
  interface Theme {
    status: {
      danger: string;
    };
  }
  // allow configuration using `createTheme`
  interface ThemeOptions {
    status?: {
      danger?: string;
    };
  }
}

• The issue is present in the latest release.
• I have searched the issues of this repository and believe that this is not a duplicate.

Current Behavior 😯

Current example in docs does not work.

Expected Behavior 🤔

Example should work.

Steps to Reproduce 🕹

Follow the docs.

The following type does work instead:

declare module "@mui/material/styles/createTheme" {
    interface Theme {
        test: string,
    }
    // allow configuration using `createMuiTheme`
    interface ThemeOptions {
        test?: string;
    }
}

Your Environment 🌎

`npx @mui/envinfo`

   System:
    OS: Linux 5.10 Ubuntu 20.04.2 LTS (Focal Fossa)
  Binaries:
    Node: 14.17.5 - /usr/bin/node
    Yarn: 1.22.11 - /usr/local/bin/yarn
    npm: 7.24.1 - /usr/bin/npm

[eps1lon]

It doesn't look like this bug report has enough info for one of us to reproduce it.

Please provide a CodeSandbox (https://material-ui.com/r/issue-template-latest), or a link to a repository on GitHub.

Here are some tips for providing a minimal example: https://stackoverflow.com/help/mcve

[wayaway-jtm]

Here's my attempt at a CodeSandbox version of my encounter with this issue: link

I may very well be misunderstanding how TypeScript is supposed to work in this instance but this is the best I've made sense of it.

[anonkey]

I have same problem but fix doesn't work for overriding subfield like adding some fields in mixins :

Subsequent property declarations must have the same type. Property 'mixins' must be of type 'Mixins', but here has type 'Mixins & { border: (color: string, width?: string | number | undefined, style?: string | undefined) => string; }'.ts(2717)

[anonkey]

Maybe repository should contain a minimal tested example of theme with module augmentation for better understanding and testing

[jimjoes]

+1 as the docs aren't clear. Would be useful to have more information on extending the theme in typescript (my particular case, extending the palette)

[isomorpheric]

The Container API was changed from mui v4 >> v5. I'd like to add the align prop, or at least a variant='centered' prop.

[mnajdova]

Can you share specific struggle that you have. We have an example of this in https://mui.com/material-ui/customization/theming/#custom-variables as already linked. What exactly is not clear and what are the suggestion for improvements?

[MauricePasternak]

I've included a small sandbox that showcases typical use cases:

1. modifying theme to include extra custom properties

2. modifying theme.palette to include extra color codes

https://codesandbox.io/s/romantic-gould-sbkc08

^ Codesandbox errors are the side product of it not playing nicely with declaration files; copy-paste both App.tsx and declaration.d.ts into your local project to see it does, in fact, work. I hope this ends up helping someone down the line.

@mnajdova I think what the MUI docs could still offer to explain is:

• Why should the Theme interface also be extended and not just ThemeOptions. I assume that my sandbox's commentary approximates the reason.

• Possibly re-organize the example to showcase separate declarations in .d.ts files rather than featuring them together in one .tsx file with the rest of the code. In fairness, the onus is on the users to read up on declarations & module augmentation and adapt accordingly. It is the translation into this other scenario that might be confusing some users when they try to attempt it.

[mnajdova]

Thanks for sharing your suggestions @MauricePasternak. I agree, we can extend/improve the docs around this. cc @samuelsycamore @siriwatknp

[AhmedAbdulrahman]

@MauricePasternak I have done the same thing for mixins as your CodeSandBox but it gives error:

Error: Property 'verticalBorders' does not exist on type 'Mixins'.ts(2339)

btw I have "@mui/material": "^5.8.6", installed.

[siriwatknp]

Thanks for sharing your suggestions @MauricePasternak. I agree, we can extend/improve the docs around this. cc @samuelsycamore @siriwatknp

I am on this.

[asmyshlyaev177]

For version v4 this worked for me.

import { createTheme } from '@material-ui/core/styles';

declare module '@material-ui/core/styles/createPalette' {
  interface Palette {
    dark: Partial<PaletteColor>;
    body: {
      standard: string;
      light: string;
    };
  }
  interface PaletteOptions {
    dark: Partial<PaletteColor>;
    body: {
      standard: string;
      light: string;
    };
  }
}

const theme = createTheme({
  palette: {
    dark: {
      main: '#1f2a44',
    },
    body: {
      standard: '#212322',
      light: '#373a36',
    },
  },
});

[MartinJaskullaTS]

@MauricePasternak

#29008 (comment) works.

Any idea how to make this work in your codesandbox?

<Checkbox color='orange'></Checkbox>

After using module augmentation to add a color to the palette, I would like it to appear as an autocomplete option for color on every component.

---

Edit:

I guess this way:
https://mui.com/material-ui/customization/palette/#typescript

declare module '@mui/material/Button' {
  interface ButtonPropsColorOverrides {
    custom: true;
  }
}

[ClemensPaumgarten]

Thanks for this #29008 (comment) . Solved it for me as well. I was looking for a solution for a while now.

I agree that documentations could be a little clearer especially regarding overriding Palette, Breakpoints etc.

[mbrookes]

Thanks for sharing your suggestions @MauricePasternak. I agree, we can extend/improve the docs around this. cc @samuelsycamore @siriwatknp

@mnajdova Reopening as it seems we agreed to improve this, but there is still some confusion.

[gerardparareda]

Absolutely agree, I've already spent two days looking through various opened and closed, new and old, MUI issues much like this one; and I still don't have working module augmentation from the library in my consumer application and feel completely clueless as there's no errors to debug, only that the augmentations doesn't happen. I feel like I've tried everything but in reality I barely know what's going on given the poor documentation of Typescript, Vite and MUI with this regard, and many examples either don't apply (like #31097) or wont work anymore.

The closest I've been to have it working is via exporting the Interface I am using to augment from the components library and then doing the module augmentation in the consumer application. But then I get errors when using createTheme since for some reason the consumer application's ThemeOptions doesn't match that of the component library, so I can't compile even though it works running the application.

[gerardparareda]

Update: After three days of trying things, I finally got module augmentation from my library in my consumer application working with ViteJS. I decided to document it:

• https://github.com/gerardparareda/module-augmentation-library-vite-mui
• https://github.com/gerardparareda/module-augmentation-app-vite-mui

I am sure there's many things I am missing or still don't understand about node bundlers and typescript modules and globals, but it's the best I've got.

To be honest, I wish MUI had more explicit examples of this, but I know ViteJS is also part of my problem.

[gerardparareda]

After some more tinkering to get it to work every time I stumbled upon the fact that my project was using version 5 of MUI and the test projects that I made were both version 6. I hadn't noticed. Because of this I was trying module augmentation with a MUI v5 project and MUI v6 library components, therefore typescript broke. Using the same version works.