Support Shadows overrides

[chris97420]

• I have searched the issues of this repository and believe that this is not a duplicate.

Summary 💡

Shadows should be configurable and extensible the same way as the colour palette

Examples 🌈

declare module '@mui/material/styles/createShadow' {
  interface DepthRange {
       0: string,
       1: string,
       2: string,
       3: string,
       4: string
  }

  interface Shadow {
      neutral: DepthRange ,
      downward: DepthRange ,
      upward: DepthRange 
  }
}

<Box sx={{ boxShadow: 'neutral.0' }}>…
<Box sx={{ boxShadow: 'downward.3' }}>…
<Box sx={{ boxShadow: 'upward.4' }}>…
<Box sx={{ boxShadow: 'neutral.3' }}>…

Motivation 🔦

Make MUI a more customizable extensible UI framework

[mnajdova]

@chris97420 the material design theme expects that array will be used for the shadows, and you can add additional shadows or redefine the array itself. If you are using createTheme from the @mui/system package for building your own design system, you can create a new structure for the shadows.

cc @siriwatknp this may be something to consider when developing the new design system.

[siriwatknp]

@mnajdova Thanks, me and @danilo-leal will take this into account for the new design system.

[theHasanas]

Any updates on this issue?

A very simple patch that worked for me was changing the file at @mui/material/styles/shadows.d.ts like this:

export interface Shadows {
  0: 'none';
  1: string;
  2: string;
  3: string;
  4: string;
  5: string;
  6: string;
  7: string;
  8: string;
  9: string;
  10: string;
  11: string;
  12: string;
  13: string;
  14: string;
  15: string;
  16: string;
  17: string;
  18: string;
  19: string;
  20: string;
  21: string;
  22: string;
  23: string;
  24: string;
};
declare const shadows: Shadows;
export default shadows;

I was then able to augment the interface and extend the theme.

[mnajdova]

We don't plan any changes to the structure at this moment. As mentioned above, you can extend it with custom values and use module augmentation to extend the type.

[theHasanas]

As mentioned above, you can extend it with custom values and use module augmentation to extend the type.

I am unable to get that to work without patching the MUI module in node_modules. Is there a better solution in which I would not need to use a patch?

I have tried these two methods:

// Tried augmenting the type as an interface
declare module '@mui/material/styles/shadows' {
  export interface Shadows {
    customShadowA: string;
    customShadowB: string;
  };
}

// Tried augmenting the type directly
declare module '@mui/material/styles/shadows' {
  export type Shadows = {
    customShadowA: string;
    customShadowB: string;
  };
}

// Like this too
declare module '@mui/material/styles/shadows' {
  export type Shadows {
    customShadowA: string;
    customShadowB: string;
  };
}

I would always get an error as such:

Duplicate identifier 'Shadows'.ts(2300)
shadows.d.ts(1, 13): 'Shadows' was also declared here.

If I am missing the point; would please be kind to show an example of I could add custom shadows and have them typed into my theme.

[theHasanas]

As I understand, you could only augment an Interface with TypeScript, and since Shadows is a type, there is no way to "extend" it.

[mnajdova]

Ah, I see, ok looks like the limitation exists. I guess we should look into this in v6, any change now I think will be a breaking change, but I may be wrong. I will leave it open in case someone wants to explore it further.

[theHasanas]

The patch works fine, changing it from Type to Interface does nothing since no Type specific features are used anywhere. But what do I know. If any maintainers could look into this it should be a very simple fix.

[mnajdova]

@theHasanas would you like to create a PR with the change? If the CI is green I think it should be safe to merge it.

[theHasanas]

Ahh, I looked again and you were right, it would indeed introduce a breaking change; the patch is modifying Shadows to be an object with indexed values instead of an array.

While MUI itself doesn't really rely on the Shadows being an array, it is a breaking change for any consumers who rely on it as an array.

Sorry for the confusion. Will just stick to the patch and hope for v6.

[mnajdova]

Thanks for looking into it @theHasanas I've added it to our v6 internal project :)