RFC: Material-UI v4 breaking changes

⚠️ No more breaking changes planned.

Tracking issue for all the breaking changes that are planned or proposed for Material-UI v4.

v4 preview: https://next--material-ui.netlify.com/

Unchecked checkboxes mean planned only. If those changes should be discussed then there either exists an existing issue or a separate one should be opened. Checked means a PR is either open or merged into next. Changes live in the next branch. Beta releases are not planned yet.

Releases

4.0.0-alpha.0

• Change UMD name to MaterialUI (PR)
• Theme, make augmentColor() immutable (issue, PR)
• Remove deprecated Button variants (see variant prop documentation). (PR)
• Remove the depreacted Button Fab code. (issue, PR)
• Drop node 6, node 8 new lowest supported runtime (PR)
• Remove typings for import Button from '@material-ui/core/es/Button' (issue, PR)
• Increase React peer dependency version to React >= 16.8.0 (PR)
• Move away from hard-coded 8px public API. For instance, I think that the following API would be much better <Grid spacing={1|2|3} /> 👍. <Grid spacing={8|16|24} /> 👎. (PR)
• Remove recompose dependency, use React.memo instead. (PR)

4.0.0-alpha.1

• Remove /es folder from icons build (PR)
• [InputLabel] Remove FormLabelClasses in favor of asterisk class (issue, PR)
• Remove deprecated Typography variants (issue, PR).
• Typography, rename property headlineMapping -> variantMapping. I’m open to better wording, at least, this one makes it obvious it’s related to the variant property. (PR)
• Link: remove block prop. (PR)

  -<Link block />
  +<Link display="block" />
  

• withTheme(options)(Component) -> withTheme(Component). There is no need for an options argument. (PR)
• Typography, change default display from block to initial, less opinionated. (PR)

4.0.0-alpha.2

• Tab, move the padding CSS from the label to the root. The more style we have on the root, the easier it’s for people to override the component. (PR)
• Add Table dense support (PR)

4.0.0-alpha.3

• forward refs in withStyles (was @material-ui/core/styles/withStyles will be @material-ui/styles/withStyles) (issue, PR)

4.0.0-alpha.4

• Remove deprecated Divider inset property. (PR)
• Rename nativeColor -> htmlColor for consistency with htmlFor. (PR)

4.0.0-alpha.5

• Modal ignore event.defaultPrevented. (issue, PR)

4.0.0-alpha.6

• Add requirement for function components that are passed via component props to forward refs (https://github.com/mui-org/material-ui/issues/13394#issuecomment-433440863 for rational). (issue)
• Typography, inherit the color by default. (PR)

4.0.0-alpha.7

• [Switch][Radio][Checkbox] Improve specification compliance (#15097)
• [Snackbar] Match the new specification (#15122)
• [TextField] Fix height inconsistency (#15217)

4.0.0-alpha.8

• [Paper] Reduce the default elevation (#15243)
• [List] Update to match the specification (#15339)
• [actions] Rename disableActionSpacing to disableSpacing (#15355)

4.0.0-alpha.9

• Modal forward ref (#15347)
• Slide forward ref (#15344)
• ClickAwayListener hide EventListener (#15420)
• Styles, remove dangerouslyUseGlobalCSS (#15140)

4.0.0-beta.0

🏁

Rejected

• Move @material-ui/core/styles/createMuiTheme -> @material-ui/core/createMuiTheme As we are moving the styling solution into its own package, this folder only focuses on the theme, we can reflect it in the name of the folder. (issue)
• Typography consitency (comment, PR)
• Prefix the style helpers that inject a default theme:

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

• Refactor the Checkbox to work like the native one (https://codesandbox.io/s/448wmxwx9, https://github.com/erikras/redux-form-material-ui/blob/v5.0.0-beta-3/src/Checkbox.js).
• Simplify the server-side rendering API
• Icon/SvgIcon change the fontSize value property default -> medium. This matches the Button size enums and the less often we use default, the better. (PR)
• Simplify the TextField code by not supporting this edge case: https://github.com/mui-org/material-ui/pull/13487/files#r230219558. (PR)
• Rename the component Grid List -> Image List to follow the specification wording. (PR)
• Rename theme.palette.type -> theme.palette.variant. We use the variant wording all over the place, what’s a “type”?
• Select / NativeSelect use InputBase over Input by default Better perf.
• Remove withMobileDialog This helper doesn’t provide any value when looking at the implementation. It would be better to educate people using withWidth(), and the upcoming hook API. (PR)
• Remove withWidth(). Use useMediaQuery instead. I would like to allow people to use custom breakpoints. withWidth is blocking this capability.
• Input, remove the dead classes that were moved to the InputBase.
• Input, rename margin?: 'none' | 'normal' | 'dense' -> margin?: false | 'normal' | 'dense'.
• Rename theme.palette -> theme.colors This should be less confusing when using the theme. I have seen any use case for an options argument, nor I can envision one now, two years later.
• ButtonBase rename focusRipple -> disableFocusRipple for consistency with our API.
• Hidden v2 Will we still need this component with the design system package? The JS version is interesting.
• Tab, rename TabIndicatorProps -> IndicatorProps.
• Reduce the large size fontSize.
• Rename the property component -> as? I need to run a Twitter Poll for this one.
• npm, rename the package folder /es -> /src. This should reduce people confusion.
• Change the controlled logic to use isControlled !== undefined (motivation).

This includes a proposal to consider the master branch as 3.x and next as 4.0.

We can either default to next which means we would need to backport changes where necessary or stay at master which would require a port of each PR to next. Either way merges between next and master should not be squashed since each commit in master is already squashed. Further squashing reduces the usability of git.

Someone with admin rights to the repo should protect the next branch against force pushes.

cc @mui-org/core-contributors

[KaRkY]

What I would suggest for v4 is unifying callbacks. Table pagination onPageChange(event, value) while onChangeRowsPerPage(event). I would suggest that all callbacks thar return a value are callback(event, value).

[jedwards1211]

theme.palette -> theme.colors

Have any devs reported being confused by theme.palette? If this change would actually help enough devs I think it would be worth it, but it would require wide-ranging changes to a lot of people’s code that uses theme.palette, so I think it’s only worth changing if very many devs have expressed confusion about this. Making a codemod isn’t as trivial as some of the other changes because of the different ways one can access theme.palette (destructuring or not, etc.)