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

crtl commented 2 years ago

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;
    };
  }
}

[x] The issue is present in the latest release.
[x] 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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

arawmedia commented 2 years ago

Any reason this was closed? I'm finding the docs extremely unclear.

isomorpheric commented 2 years ago

Why is this closed, this is accurate...

jimjoes commented 2 years ago

+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 commented 2 years ago

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

maulerjan commented 2 years ago

@mbrookes Why did you close a legit issue with no explanation?

The documentation is clearly misleading, the example in it doesn't work.

mbrookes commented 2 years ago

It was closed because it was tagged incomplete. I'll reopen for now.

mnajdova commented 2 years ago

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 commented 2 years ago

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.

mbrookes commented 2 years ago

@mnajdova ?

mnajdova commented 2 years ago

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

AhmedAbdulrahman commented 2 years ago

@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 commented 2 years ago

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

I am on this.

asmyshlyaev177 commented 1 year ago

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 commented 2 months ago

@MauricePasternak

https://github.com/mui/material-ui/issues/29008#issuecomment-1172979731 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 commented 2 months ago

Thanks for this https://github.com/mui/material-ui/issues/29008#issuecomment-1172979731(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 commented 1 month ago

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 commented 2 weeks ago

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 https://github.com/mui/material-ui/issues/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 commented 1 week ago

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:

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 commented 1 week ago

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.

mui / material-ui