[RFC] Restructure the keys inside the theme by component name

Summary

This RFC proposes slightly different structure to the theme, by moving the components as first key, and nesting the existing keys (overrides, props and variants - will be added with https://github.com/mui-org/material-ui/pull/21648) inside. As we are doing this breaking change, we may even consider renaming the existing keys based on this https://github.com/mui-org/material-ui/issues/21012#issuecomment-629161024 to cssOverrides and defaultProps.

Changes

Current:

const theme = createMuiTheme({
  overrides: {
    MuiButton: {
      root: {
        fontSize: 20,
      },
    },
  },
  props: {
    MuiButton: {
      disableFocusRipple: true,
    },
  },
  variants: {
    MuiButton: [
      {
        props: { variant: 'dashed' },
        styles: { border: '2px dashed grey' },
      }
    ],
  },
});

Proposed:

const theme = createMuiTheme({
  components: {
    MuiButton: {
      cssOverrides: {
        root: {
          fontSize: 20,
        },
      },
      defaultProps: {
        disableFocusRipple: true,
      },
      variants: [
        {
          props: { variant: 'dashed' },
          styles: { border: '2px dashed grey' },
        },
      ],
    },
  },
});

Motivation

Think component first.

With the proposed definition all theme definitions related to one component can be easily discovered and defined together. It’s also interesting if later on, developers have a concern about tree-shaking and want to move the configuration from the theme singleton to wrapper components they import.

Drawbacks

Other than the change being breaking, I don’t see any other drawback with the proposed restructuring.

Prio-arts

Same approach in

• https://www.vue-tailwind.com/
• https://next.chakra-ui.com/docs/theming/overview#where-to-put-the-style-config

[ryancogswell]

If we were to unify the terminology, I think I prefer cssOverrides and css rather than styleOverrides and styles. I like how cssOverrides ties more clearly to the CSS portion of the API documentation. styles makes me think of inline styles which might not give quite the right mental model – I assume the CSS for a variant will support media queries and pseudo classes (just like you can do within one of the rules of the cssOverrides). I think the styles name might provide an impression that it wouldn’t support those aspects (since they aren’t supported by inline styles).

[ryancogswell]

I think the overall structure change is nice, but I think it is important to add a function to ease migration such as createMuiThemeFromV4Structure that would take care of reorganizing the props and overrides portion of the passed in theme as necessary. Then developers could import that instead of createMuiTheme if they want to put off reorganizing their theme to the new structure.