[RFC] Material-UI v5 🚀

[oliviertassinari]

Introduction

Material-UI v4 was released 10 months ago, per our release schedule. It's time to plan for v5.
Our GitHub milestone has a due date for October 1st 2020, and while I doubt we will release in time, planning 6 months ahead seems relevant.

Developers made it clear in the past that they don't enjoy breaking changes. This is feedback we took into consideration when designing our versioning strategy, and for each minor/patch releases. The result was to commit to a minimum of 1 year between each major release.

At the same time, the v0 to v1 upgrade was a major breaking change (a rewrite with a brand new API) and yet it was successful. I think that we should be willing (taking the risk) to make bold changes, as long as they fit in the direction we see the community going in the long term (with Material-UI empowering it).

Structural changes

1. Unstyled components

Similar to Angular Material CDK components (Component Development Kit) #6218.

In practice, it could be a new hook version of all the components, something we have started to experiment with the useAutocomplete and usePagination in the lab.

The problem:

• The React OSS component community is fragmented. You will find both standalone components for a specific problem, as well as and a growing number of component libraries, with a wide range of API consistency, a11y, bug density, performance, bundle size, quality, and support.
• Styling solution usage is fragmented. We can get a glimpse of this by looking at the CodeSandbox usage stats for the style interoperability page:
  • plain css: 34%
  • styled components: 30%
  • global css: 18%
  • css modules: 12%
  • emotion: 5%
• Developers and designers use different design systems. Material Design doesn't have a monopoly.
• How can we help with the unstyled story of notistack, raised by @iamhosseindhv?

Why this solution?:

• This will enable Material-UI to stay relevant in the long term. This is a cornerstone of our strapline. It will shift the developer's perception, that Material-UI is, at its core, about providing material to build UIs.

React components for faster and easier web development. Build your own design system, or start with Material Design.

• Talking with backend and fullstack users, we know that they are craving for a single component store rather than having to deal with a wide range of dependencies. We could expect the same from front-end developers.
• This new "offering" should better resonate with front-end developers. We could expect to gain more and higher quality contributions from the front-end community thanks to this shift.
• Based of our current trust, usage, and exposure in the React community, we are well-positioned to gain usage with this new "offering".
• Maintaining standalone components is rarely sustainable. I have seen too many projects left abandoned. But by aggregating them in Material-UI, it helps our flywheel. It can incentivize new maintainers to work on the OSS. It can also strengthen our current monetization channels and invest resources back into the OSS components.
• It's important to support different style engines and design systems.

2. Full strict mode support

#18018, #13394

The problem:

• While developers can set up strict mode in their app to identify incorrect patterns, Material-UI prevents them from keeping this mode enable on a daily basis, as there would be too much noise in the console. We have, for example, disabled it for the Material-UI documentation.

Why this solution?

• It's the future.
• It helps with the unstyled story.

3. Migrate to styled-components

#6115, #16947

The problem:

• We have left important issues related to our styling solution unhandled over the last few months: streaming, strict mode, performance, CSS template support, style functions, class name mismatch, etc.
• We need to support dynamic props, this is important for the features we want to implement on the components.
• JSS popularity didn't stick with the front-end community.

Why this solution?

• A migration to styled-components is our most requested (upvoted) issue to date.
• We want to remove the need for the majority of developers to bundle two CSS-in-JS runtimes.

It could be interesting to provide a choice between different style engines. v5's users would be able to replace @material-ui/styles with react-jss.

4. Enable the use of @material-ui/system's props in the core components

#15561

The problem

• Naming things is hard.
• Indirections can be inefficient.

Why this solution?

This is mainly driven by the positive feedback Tailwind and styled-system have had recently in the community. I enjoy the pattern a lot for one-off layout problems. It's frustrating that only the Box component supports it. I think that it should also cover #6140.

<Typography textAlign={{ xs: 'left', md: 'center' }} />
<Button mt={3}>

Regarding the implementation and final API, we could still reconsider the tradeoff (relying on global class names rather than style functions).

5. Allow the use of dynamic theme variants and colors

#15573 & #13875. Allow breakpoints customization #11649.

---

I was wondering about revamping the theme structure to match System-UI Theme Specification
but we don't see a clear win so far.

Material-UI's theme structure, on its own, is a specification, the structure is set.
Assuming that Material-UI aims to support a wide range of components (unstyled or not), matching this spec, not just Material Design,
I fail to see a strong advantage a different constraint could yield.

On the cost side, using theme-specification would require to drop some of the features of our theme and require breaking changes.
The benefit isn't obvious, but it's something to consider.

Regarding styled-system. I think that we should re-evaluate if we still need @material-ui/system.

Material Design

✅ Checklist

• [Checkbox] Make color="primary" the default ([Checkbox] Make color="primary" default #26002)
• [Paper] Dark mode brighening based on elevation Support dark mode brighening based on elevation #18309 ([Paper] Support dark mode brightening based on elevation #25522)
• [Snackbar] Dark mode color [Snackbar] Shouldn't be light in dark mode #24438
• [Tabs] Improve color management [Tabs] Improve color management #24286
• [Switch] Make color="primary" the default (BC: [Switch] Make color primary default #26182)
• [Radio] Make color="primary" the default (BC [Radio] Make color primary default #26180)
• [Tabs] Remove min-width media query [Tabs] Remove min-width media query #15824 (BC: [Tabs] Update min & max width and remove minWidth media query #26458)
• [Select] Update to match the specification [Select] Follow material design guidelines #18493 (BC: [Select] Open popup below button #26200)
• [Dialog] Flatten DialogTitle DOM structure [Dialog] Flatten DialogTitle DOM structure #19696 (BC: [Dialog] Flatten DialogTitle DOM structure, remove disableTypography #26323)
• [Button] Reduce the duration of the transition from 250ms to 200ms [website] Add Join Us block #24521 (comment) I don't think this is worth doing now - edited by @siriwatknp
• [Autocomplete] Consistency with select [Select] Consistency with Autocomplete #18136 [move to v5.1]
• [AppBar] Improve the design [AppBar] Make dark by default for dark themes #18308 (BC: [AppBar] Fix background color on dark mode #26545)
• [Checkbox][Switch] Remove dependency on IconButton Can't override IconButton styles in theme without affecting Checkbox and Switch #21503 (BC: [SwitchBase] Replace IconButton with ButtonBase #26460)
• [docs] Use the default theme [docs] Sync default theme with the theme used by the documentation #22112, Dark mode not applying to textfield or buttons #21040 (comment)
• [theme] Dark mode colors Update dark theme primary and secondary colors #18378
• Material Design states Implement Material Design States #10870 deferred @siriwatknp
• [Tabs] Update to match the specification [Tabs] Update to match the specification #15324 deferred (can be workaround by css) @siriwatknp
• [theme] Improve the breakpoints values [theme] Improve the breakpoints values #21902
• [Menu] Remove MenuItem dependency on ListItem [Menu] Remove MenuItem dependency on ListItem #21587
• [Slider] Update to match the spec [Slider] Update to match the specification #20153
• [IconButton] Update default size and add large [IconButton] Improve size values #24045
• [Button] Update to match the spec [ButtonBase] Inconsistent ripple style with the material specs #19664 deferred @siriwatknp

Lab to core components

I think that we can aim to move the following components from the lab to the core:

✅ Components

• Alert ([Alert] Move from lab to core #22651)
• Autocomplete ([Autocomplete] Move from lab to core #22715)
• AvatarGroup [AvatarGroup] Move to the core #18869 ([AvatarGroup] Move from lab to core #23121)
• Pagination ([Pagination] Move from lab to core #22848)
• Rating ([Rating] Move from lab to core #22725)
• Skeleton ([Skeleton] Move from lab to core #22740)
• SpeedDial (finally!) ([SpeedDial] Move from lab to core #22743)
• Toggle Button ([ToggleButton] Move from lab to core #22784)

The only component I have would propose to handle later on is the TreeView.
We still have a couple of important features to implement, and might need to change the API to ship these features. Once we do, we'll start to get more adoption, so the more likely it is that developers will uncover root issues.

Supported browsers

While we plan to keep IE 11 support until v6,
We will look into proposing different proposing entry points #18447.
and if we can drop older browsers' versions #15496.

Deprecations

✅ List of breaking changes we can introduce with a deprecation during v4.

• Drop createStyles (see [RFC] Material-UI v5 🚀 #20012 (comment))
• [Portal] Remove Portal disablePortal prop. Maybe we can implement the logic at the Portal component consumer level. [Portal] Support any children node #18692 (comment)
• [theme] Remove theme.mixins.gutters. I don't believe we document them, nor are they used. (BC: [theme] Remove theme.mixins.gutters #22109, Dep: [theme] Deprecate theme.mixins.gutters #22245)
• [theme] Rename theme type -> mode. While the spec use "schema", saying "dark mode" seems to be more common, e.g https://css-tricks.com/dark-modes-with-css/. (BC: [theme] Rename type to mode #22687, "Dep": [theme] Fix Hidden breakpoints issues and updates the migration guide #22702 – adaptV4Theme())
• [theme] Rename color helpers [colorManipulator][docs] Document the color helpers #13039 (comment). (BC: [theme] Rename fade to alpha #22834, Dep: [theme] Deprecate fade color utility in favor of alpha #22837)
• [test] Remove enzyme test helpers. They are legacy. It's also a good opportunity to upgrade the documentation [test] Improve the guide documentation page #17070. (BC: [core] Remove /test-utils #21855, [docs] Update testing guide #21863, Dep: [test] Deprecate /test-utils #24074)
• Remove the onX* transition props from Dialog, Snackbar, Menu & Popover, Improve transition documentation #17047 (comment).
  (Snackbar BC: [Snackbar] Remove transition onX props #22107, Dep: [Snackbar] Deprecate transition onX props #22206; Popover BC: [Popover] Remove transition onX props #22184, Dep: [Popover] Deprecate transition onX props #22202; Dialog BC: [Dialog] Remove transition onX props #22113, Dep: [Dialog] Deprecate the transition onX props #22114; Menu BC: [Menu] Remove transition onX props #22212, Dep: [Menu] Deprecate transition onX props #22213)
• Remove RootRef, it relies on ReactDOM.findDOMNode(component) that is already deprecated. (BC: [RootRef] Remove component #21974, Dep: [RootRef] Deprecate component #24075)
• [icons] Change default fontSize prop's value: default -> medium, for consistency with the other components [Icon] Change default fontSize name #14993. (BC: [Icon][SvgIcon] Change default fontSize from default to medium #23950, Dep: [Icons] deprecate default value for fontSize in favor of medium #23951)
• [Accordion] Normalize focusVisible logic (BC: [Accordion] Normalize focusVisible logic #22567, Dep: [Accordion] Deprecate classes.focused #24083)
• [Avatar] Rename variant circle -> circular for consistency [RFC] Renaming API for consistency #21964. (BC: [Avatar] Rename variant circle -> circular for consistency #22015, Dep: [Avatar] Add circular variant #22090)
• [Badge] Rename overlap circle -> circular and rectangle -> rectangular for consistency [RFC] Renaming API for consistency #21964. (BC: [Badge] Rename overlap circle -> circular and rectangle -> rectangular for consistency #22050, Dep: [Badge] Add overlap circular and rectangular #22076)
• [CircularProgress] Remove one variant. Kill the current determinate variant, rename static => determinate. [Button] Add loading support #7223 (comment). (BC: [CircularProgress] Remove static variant, simplify determinate #22060, Dep: [CircularProgress] Backport simplified determinate style & deprecate static #22094)
• [Collapse] Add orientation and horizontal support (BC: [Collapse] Add orientation and horizontal support #20619, Dep: [Collapse] Deprecate collapsedHeight #24079)
• [Dialog] Remove withMobileDialog. [Dialog] Prepare deprecation of withMobileDialog #14992. We have already removed it from the documentation. (BC: [withMobileDialog] Remove HOC #23202, Dep: [Dialog] Add deprecation warning for withMobileDialog #23570)
• [Dialog][Modal] Remove disableBackdropClick (BC: [Dialog][Modal] Remove disableBackdropClick #23607, Dep: [Modal][Dialog] Deprecate duplicate props with onChange #24081)
• [Fab] Rename Fab round -> circular for consistency [RFC] Renaming API for consistency #21964. (BC: [Fab] Rename round -> circular for consistency #21903, Dep: [Fab] Deprecate variant="round" #24080)
• [Grid] Rename prop justify -> justifyContent to match system API. (BC: [Grid] Rename justify prop to justifyContent #21845, Dep: [Grid] Add deprecation for justify prop rename #24078)
• [GridList] Rename component to ImageList as more intuitive and better match the wording of the Material Design spec [GridList] Deprecate, rename ImageList #14994. (BC: [GridList] Rename to ImageList #22311, Dep: [GridList] Rename to ImageList & add deprecation warnings #22363)
• [GridList] Rename Tile to Item (BC: [ImageList] Rename Tile to Item #22385, Dep: [GridList] Rename to ImageList & add deprecation warnings #22363)
• [GridList] Refactor using CSS grid & React context (BC: [ImageList] Refactor using CSS grid & React context #22395, Dep: [GridList] Rename to ImageList & add deprecation warnings #22363)
• [GridList] Rename spacing prop to gap to align with the CSS attribute. (BC: [ImageList] Refactor using CSS grid & React context #22395, Dep: [GridList] Rename to ImageList & add deprecation warnings #22363)
• [GridList] Rename the GridList cellHeight prop to rowHeight. (BC: [ImageList] Refactor using CSS grid & React context #22395, Dep: [GridList] Rename to ImageList & add deprecation warnings #22363)
• [GridList] Rename the GridListItemBar titlePosition prop to position. (BC: [ImageList] Refactor using CSS grid & React context #22395, Dep: [GridList] Rename to ImageList & add deprecation warnings #22363)
• [Modal] Add support for onKeyDown and remove onEscapeKeyDown (BC: [Modal] Add support for onKeyDown and remove onEscapeKeyDown #23571, Dep: [Modal][Dialog] Deprecate duplicate props with onChange #24081)
• [Portal] Remove onRendered -> ref. context: [Modal] Refactor tests to remove internal accesses #16262 (comment). (BC: [core] Remove onRendered from Modal and Portal #22464, Dep: [Modal][Portal] Deprecate onRendered #24082)
• [TextareaAutosize] Rename rowsMax -> maxRows for consistency, (BC: [TextareaAutosize] Rename rowsMax->maxRows & rowsMin->minRows #21873, Dep: [TextareaAutosize] Deprecate rowsMax->maxRows & rowsMin->minRows #23530)
• [Table] Rename onChangeRowsPerPage -> onRowsPerPageChange, onChangePage -> onPageChange for consistency. It's a good opportunity to mention this API design choice in the documentation: https://jaketrent.com/post/naming-event-handlers-react/#more-complicated-naming; (BC: [Table] Rename onChangeRowsPerPage, onChangePage #22900, Dep: [Table] Add deprecation for renamed TablePagination props #23789)
• [theme] Remove the fade color helper [colorManipulator][docs] Document the color helpers #13039. (BC: [theme] Remove fade color helper #25895)
• [Button] Remove the buttonRef prop. (BC: [ButtonBase] Remove buttonRef prop #25896, Dep: [ButtonBase] Add warning for buttonRef removal #25897)
• [Popover] Remove getContentAnchorEl prop. This method was present to implement a macOS native select like experience. It complicates the implementation of the Popover and could prevent us from moving [Select][material-ui] Don't lock the body scroll and make it non-modal select #17353 forward.
• [TextField] The position prop should be required in InputAdornment. (BC: [TextField] Make the position prop required in InputAdornment #25891, Dep: [TextField] Add isRequired to position prop in InputAdornment #25912)
• [Button] Change LoadingButton prop pending to loading [Button] Change LoadingButton prop pending to loading #21593 (BC: [Button] Rename pending prop to loading in LoadingButton #25874)
• [SwitchBase] Remove second onChange argument: event.target.checked is enough. (BC: [Checkbox][Switch] Remove checked argument from onChange #25871)
• [theme] Remove the exported theme.typography.round helper. (BC: [theme] Remove theme.typography.round helper #25914, Dep: [theme] Add warning for theme.typography.round deprecation #25916)
• [theme] Remove legacy v4 deprecation Object.defineProperty(spacing, 'unit', {
• ?[theme] Replace theme.direction === 'rtl' -> theme.isRtl.
• [Table] Rename padding="default" -> padding="normal" (BC: [Table] Rename padding="default" to padding="normal" #25924, Dep: [Table] Deprecate padding="default" #25990)
• [theme] Remove function width(key) { return values[key]; }, it's useless. (BC: [theme] Remove theme.breakpoints.width helper #25918, Dep: [theme] Add warning for theme.breakpoints.width deprecation #25993)
• [theme] Rename createMuiTheme -> createTheme to match ThemeProvider's theme prop. (BC: [theme] Rename createMuiTheme to createTheme #25992, Dep: [theme] Deprecate createMuiTheme #26004)
• ?[theme] Flatten colors to support CSS variables as theme option Support CSS variables as theme option #12827 later

For a list of committed breaking changes and associated deprecations, see: #22074

Breaking changes

Unlike the previous section, these are breaking changes we can't gracefully warn against.

• ? [AppBar] Change default position from fixed to static. What's the most frequent AppBar position?

• ? Rotate 180° icons to only include one? Involve: TablePagination, Pagination or DatePicker.

• [Slider] Fix the class names naming. track and rail means the same thing.

• [Container] Revisit max-width values to be more useful [theme] Improve the breakpoints values #21902

• [core] Only support node >= 10 [core] Use node 10 in every CI/CD pipeline #19301 (comment) ([core] Ship modern bundle #22814)

• [theme] Remove dead palette.text.hint key

• [theme] Always return value with 'px' unit in the spacing function breaking change enhancement Always return value with 'px' unit in the spacing function #16205 ([theme] Always return default spacing value with px units #22552)

• [theme] Breakpoints down use interval. Same as https://github.com/ionic-team/ionic/blob/master/BREAKING.md#display-classe [Breakpoints] functions down() and between() adds +1 to index #13448 ([theme] Improve breakpoints definitions #22695)

• [Chip] Change variant default value [Chip] variant default value #18914 ([Chip] Rename default variant to filled #22683)

• [Divider] Use border instead of block content ([Divider] Use border instead of background color #18965)

• [Pagination] Rename round -> circular for consistency [RFC] Renaming API for consistency #21964. ([Pagination] Rename round -> circular for consistency #22009)

• [Popper] Figure out what we do with popper.js, we have 4 options upgrade, remove it, rewrite it, fork it Popper changed home #19358 ([Popper] Upgrade to popper.js to v2 #21761)

• [Skeleton] Rename variant circle -> circular and rect -> rectangular for consistency [RFC] Renaming API for consistency #21964. ([Skeleton] Rename variant circle -> circular and rect -> rectangular for consistency #22053)

• [Slider] Custom tooltip ignores valueLabelFormat and valueLabelDisplay [Slider] Custom tooltip ignores valueLabelFormat and valueLabelDisplay #17905.

• [Snackbar] Change default position. Change the default position of the snackbar on desktop to bottom left. This will better be aligned to the behavior of material.io, Gmail, Google Keep, notistack, etc. ([Snackbar] Change the default position on desktop #21980)

• [Stepper] Remove Paper component [Stepper] Remove Paper component #18423 ([Stepper] Remove Paper and built-in padding #22564)

• [Textfield] Change the default variant -> outlined. Per https://medium.com/@brianisrighthere/material-studies-text-fields-f029b3b38020. ([TextField] Change default variant from standard to outlined #23503)

• [CssBaseline] Apply body2 -> body1 Applying body2 styling to the body element causes weird behavior that can't be overriden #17100. ([CssBaseline] Change body font size to body1 (1rem) #24018)

• [types] Remove deprecated SimplifiedPropsOf/Simplify types. [core] Remove deprecated SimplifiedPropsOf/Simplify types #24750

  https://github.com/mui-org/material-ui/blob/7a4bd5807959b0069be9b5f40ba80eaae9ace2c8/packages/material-ui/src/OverridableComponent.d.ts#L65-L74

• [typescript] Only support TypeScript 3.8 and onwards. Omit was added in 3.5, can be removed from @material-ui/types.

• [Select] Change the default variat as TextField [Select] Improve description on how it extends the Input components #24180 (comment). [Select][FormControl] Make outlined variant the default one #24895

• [Box] Remove the clone prop [system] Remove Box clone prop #18496 (BC [Box] Remove the clone prop #26031)

• [core] Remove deprecated innerRef prop, forwardRef do the job now. (BC [core] Remove deprecated innerRef prop #26028)

• [Select] Remove labelWidth prop [Select] Remove labelWidth prop #22799 (BC: [Select] Remove labelWidth prop #26026)

• [Hidden] Remove component [Hidden] Remove component #19704. The CSS API can be replaced with the Box, the JS API can be replaced with useBreakpoint or useMediaQuery. (BC: [Hidden] Remove component #26135)

• Remove withWidth, replace with useBreakpoint() [withWidth] Remove the API #17350. (BC: [withWidth] Remove API #26136)

• [theme] Remove MuiThemeProvider alias. ThemeProvider is enough. https://github.com/mui-org/material-ui/pull/22791/files#r499154080 (BC: [theme] Remove MuiThemeProvider alias #26171)

• [Autocomplete] Rename the reasons for consistancy. 'create-option' is not OK.
  It should be camelCase. (BC: [Autocomplete] Rename values of the reason argument #26172)

• [Select] Replace with [SelectField][material-next] Introduce new component #21782 (PR [SelectField] new SelectField component #26221) Do in the lab instead

• [Autocomplete] Polish the pseudo-classes customization API [Autocomplete] can't change option highlight color #19692 (BC: [Autocomplete] Apply .Mui-focused instead of data-focus on the focused option #26181)

• [Grid] Remove the type exports, developers don't need them. Export useful developer Typescript types #19572 (comment) (BC: [Grid] Remove unnecessary type exports #26187)
  https://github.com/mui-org/material-ui/blob/9f3c45b1f7fbb7c2095b61c30a3e0659f21dd5cf/packages/material-ui/src/Grid/Grid.d.ts#L8

• [Select] CSS API's 'selectMenu' maps to the same element as 'select' [SelectMenu] CSS API's 'selectMenu' maps to the same element as 'select' #11646. (BC: [Select][NativeSelect] Polish CSS classes #26186)

• [Autocomplete] getOptionSelected is confusing, rename to optionEqualValue [Autocomplete] Rename getOptionSelected to optionEqualValue #24855 (BC: [Autocomplete] Rename getOptionSelected to isOptionEqualToValue #26173)

• [core] Normalize file location. Module not found @material-ui/core/ThemeProvider when minimizing bundle size in create react app #23208 (BC: [core] Move StyledEngineProvider to @material-ui/core/styles #26265)

• Improve the color prop handling [RFC] color prop API #13028 [move to v5.1]

• [List] Improve <ListItem button> [List] Improve ListItemSecondaryAction handling #13597 (PR: [List] extract button from ListItem to ListItemButton #26446)

• Check if Button > span still required. (PR: [Button] Remove label span #26666, [IconButton] Remove label span #26801)

• [CssBaseline] Improve CSS reset, can we leverage any of https://hankchizljaw.com/wrote/a-modern-css-reset/, https://github.com/sindresorhus/modern-normalize/blob/master/modern-normalize.css deferred @siriwatknp.

• Remove wrapper in BottomNavigationAction

• ref attribute is not the root element [Switch] ref attribute is not the root element #19613 [move to v5.x]

---

Timing

I think that we can try the following:

1. Deprecation preparation. (starts now)
2. Create the next branch, publish the next versions under https://next.material-ui.com/ and the next npm tag. (April?). Stop all efforts on the v4.x version. Put the master branch (v4.x) in a low maintenance mode, only handle security fixes.
3. Work on the above items, in whatever order is simpler, keep the same release schedule, once a week, with alpha first.
4. Once we have handled all the breaking changes and confidence with the architectural choices move to a beta stage. Once we are confident with the implemented features, start release candidates.

Current progress 109/109

Array.from(document.querySelectorAll('.contains-task-list')[2].children)
.concat(Array.from(document.querySelectorAll('.contains-task-list')[3].children))
.concat(Array.from(document.querySelectorAll('.contains-task-list')[1].children))
.concat(Array.from(document.querySelectorAll('.contains-task-list')[0].children))
.reduce((acc, item) => {
  if (item.querySelector('input[type="checkbox"]:checked')) {
    acc.done += 1;
  }
  acc.total += 1;
  return acc;
}, { total: 0, done: 0 });

[ValentinH]

Really detailed plan and it looks good to me.

The only thing that scares me about is the styled component part.

v5's users would be able to replace @material-ui/styles with react-jss.

Does react-jss includes all the features of @material-ui/styles? Specifically the awesome TS support for the return type of useStyles()?

[dmtrKovalenko]

Unstyled components

I think that providing hooks is not a really best solution for making custom design systems. I know that some companies using material-ui like

// packages/design-system
export * from '@material-ui/core'

export const ThemeProvider = ({ ...props }) => 
  <ThemeProvider theme={ourCustomStyledMuiTheme()} /> 

// then in app code
import { Button } from '@my-project/design-system' 

And this is a really powerful way to build custom design, based on best practices and documentation of material-ui. The main problem here is only bundlesize bloating. You have no way to remove from the bundle overridden css. Unstyled components can solve this problem just fine.

But the proposed solution with hooks will may them to write custom components, custom dom structure – that’s why I don't think it will not become really popular.

Should it work something like this? This will make building design system overcomplicated and require everybody to rebuild html structure, which in its turn can break accessibility 😢

import { useButton } from '@material-ui/core'

const buttonProps = useButton()
export const Button = () => <button {...buttonProps} /> 

Proposal

I propose to provide an additional exported components but without any css. So they will be just empty html components with the logic. Thus any company will be able to handcraft custom design for provided components and use all the power of material-ui accessibility, types, documentation and so on.

export * from '@material-ui/core/unstyled'

How? For example, we can make a custom babel plugin that will, for example, remove all the css code from components and will leave only class names.

[yordis]

Personally, before tackling the unstyled components, I would make sure to divide it into two categories: Behavioral and UI. Or at least have clear boundaries about this in the source code, now with hooks, probably most things would become as part of a hook rather than as part of the component body.

Behavioral components expose functionality either by hooks or by elements that don't affect the UIs as much, for example, Slider, Click Away Listener, Popovers, Portals.

While UI is purely how things look.

[oliviertassinari]

Does react-jss includes all the features of @material-ui/styles? Specifically the awesome TS support for the return type of useStyles()?

@ValentinH I don't have the details on this question. If it doesn't, it will be a great opportunity to port these advantages back to react-jss.

I think that providing hooks is not a really best solution for making custom design systems.

@dmtrKovalenko I like the proposal. I have been wondering about going into this direction. I think that solving this problem will be very interesting, it's a complex problem with many use cases to consider and strong tradeoffs to take. In any case, I doubt that hooks can be 100% of the answer.

[saulshanabrook]

We are considering using Material UI in JuyterLab (jupyterlab/jupyterlab#7574) and was wondering about this point:

It could be interesting to provide a choice between different style engines. v5's users would be able to replace @material-ui/styles with react-jss.

This sounds like an interesting and useful idea and I am curious if other libraries provide compatibility with different style engines. Ideally, it would be nice to be able to switch dynamically between these frameworks and just generating plain CSS, by just changing some config or build value and not having to rewrite all our components. 🤷‍♂

However, I haven't though very deeply about the topic. Please let me know if this has already been discussed somewhere. Also curious if other libraries have experimented with this technique.

[oliviertassinari]

Also curious if other libraries have experimented with this technique.

@saulshanabrook I'm not aware of any deployed prior work on this matter.

We are considering using Material UI in JuyterLab (jupyterlab/jupyterlab#7574) and was wondering about this point:

This is awesome, I'm going to following this thread to see if I can bring in any facts.

[balazsorban44]

Really well-written!

I have a proposal(?) for:

[theme] Rename theme type -> mode. While the spec use "schema", saying "dark mode" seems to be more common, e.g https://css-tricks.com/dark-modes-with-css/.

I recently started implementing dark mode for our project at our company, and more than once (actually pretty much all the time) I do either of these:

1. When accessing theme.palette.type is to check for theme.palette.type === "dark", and write it to a isDark (doing this inside makeStyles(), when I create classes for components),
2. I use a custom hook useTheForce().isDark (🤓) (which is just useTheme().palette.type === "dark")

Would it be easier to just expose theme.palette.isDark (name can be anything) as a boolean, either next to the proposed theme.palette.mode or dropping mode entirely. Is it possible to implement more than light and dark at all? If yes, I can understand the reason behind using a string, otherwise one have to write some boilerplate to access this simple true or false value.

Do tell if there is a reasoning behind it, or I could do better than the above-mentioned options.

Looking forward to Material UI v5! 🎉

[oliviertassinari]

@balazsorban44 Interesting, we could extend the discussion to theme.direction === "rtl" vs theme.isRtl.

[balazsorban44]

I don't have a case for that (yet?), but that looks to be the same situation, yes.

Except maybe that there are only right-to-left and left-to-right. I guess theoretically it is allowed to add more than "light" and "dark" options to mode though, or is there any underlying restriction (Can MUI handle more than two modes?) Still, I would argue that accessing dark mode is so common that it should be exposed as a boolean.

Are there any reasons not to include both (the proposed mode as a string and an isDarkMode boolean) variants?

Also, is it possible to expose an accompanying function (eg.: changeMode) to be able to quickly change between modes (and RTL)? Right now, one has to use createMuiTheme in some kind of a provider above ThemeProvider that has a simple mode state (which is used to toggle the passed theme to ThemeProvider) and a setMode setter, that can be used to switch between modes from anywhere in the app). If a setter would be exposed on useTheme(), an extra context could be spared here, as this only "syncs" the mode's state in ThemeProvider.

[oliviertassinari]

@balazsorban44 thank you for bringing your perspective on the matter. It's also interesting to look at the strategy we had in v0: https://v0.material-ui.com/#/customization/themes. Considering the idea that we want to provide multiple themes (Material Design, Gmail, Firebase, Material Studies, Fluent, Ant Design, Chakra, Bootstrap, High contrast, etc), we could consider handle the dark mode as a standalone theme 🤔.

is it possible to expose an accompanying function (eg.: changeMode) to be able to quickly change between modes (and RTL)?

See the discussion in #20495.

[popuguytheparrot]

I'm Concerned for DX in Developer Tools.
I would like to avoid such nesting without to the use of filters.
For example, if this possible to change hoc withStyles to hook, and forward ref to hook.
Fix Anonymous names.

[popuguytheparrot]

I wrote about it. The solution through the filter does not solve the problem. it is important to refuse in favor of hooks

[mwhitney-butter]

i've searched far and wide for any issues or tasks regarding migrating the DataGrid component to v5 but havent found any yet. I've started a brand new project currently using the beta version of @material-ui/core@next and everything was fine until i tried to use the DataGrid. i get an error if i don't have the old material styles package installed specifically for the DataGrid. what's the plan for DataGrid?

[oliviertassinari]

i've searched far and wide for any issues or tasks regarding migrating the DataGrid component to v5 but havent found any yet.

@mwhitney-butter The data grid component is compatible with v5, as you can see in this demo https://codesandbox.io/s/material-demo-forked-tiwo9. However, it still relies on JSS, we haven't migrated to emotion yet. We have this milestone to make progress with a perfect integration with v5: https://github.com/mui-org/material-ui-x/milestone/10.

This issue mui/mui-x#1902 might be the one you are the most interested in. The current target is to drop v4 support in the data grid once v5 is stable.

[jedwards1211]

I don't think I'll ever have time to migrate my entire app to Emotion. It looks like I can keep using the JSS stuff via @material-ui/styles if I upgrade to v5, but that would mean both Emotion and JSS wind up in my app bundle, right? That would be too much, I'll have to stick with v4 if that's the case. If I run into issues with v4, will I be out of luck for any fixes though?
(Or will there be continued v4 support via a Tidelift subscription?)

[oliviertassinari]

@jedwards1211 We only fix major issues on the core components of v4 (we haven't fixed a lot in 12 months, to be honest). This is done to avoid version fragmentation in the community.

[eric-burel]

I am investigating v5 styled API. I've been using Styled Components for a while (~2017), so I am progressively trying to adapt to new patterns.

At this point I think there is a (perfectly normal) lack of guidelines about styling our own components.

• Will makeStyles be progressively deprecated? It has an important place in the v5 docs at the moment https://next.material-ui.com/styles/basics/
• On the contrary, styled tag as a small place while many people are currently using either Styled Components or Emotion styled tag. https://next.material-ui.com/system/styled/
• No doc about the string template syntax (while from my experiment it seems to work). It would be nice to keep the same behaviour as Styled Components and even maybe keep using the same syntax highlighting plugins. I don't know what Emotion proposes but I guess it's similar.
• Best practices might need to be translated. For instance, I've just found out this gold article from Josh Comeau (https://www.joshwcomeau.com/css/styled-components/), but I am not sure how to translate into Material UI styled. Using the string template approach would probably help as many learning resources coming from Styled Components are using this syntax (another one I loved: https://frontendmasters.com/courses/design-systems/)

[CloutProject]

I merged my entire codebase to Material-UI v5 and everything went well. However, there is one thing that annoyed me: the styled api doesn't seem to support styled-components syntax for regular html tags (where you use a dot instead of parentheses). For instance: one would expect to be able to do the following:

const MyStyledComponent = styled.div`
  padding: 16px 24px;
`;

I know I can achieve the same behavior with the parentheses syntax, but is there any particular reason why we cannot use the dotted one?

[oliviertassinari]

@CloutProject Note that not all the styled implementation supports this shortcut, e.g. https://github.com/cristianbote/goober#comparison-and-tradeoffs. Goober doesn't support it in the base package to minimize bundle size.
It also leads to two way to do the same things, developers are left wondering if they should either use styled('div') or styled.div. 👍 for not supporting this API.

An issue slightly related: #23220.

[mnajdova]

Looks like all planned work has finished, so we believe we can close this one.

[dimitropoulos]

@oliviertassinari (cc: @CloutProject) I think the point you make is very valid, however the problem is that the styled.div syntax is far far far more common. The styled-components docs pretty much exclusively uses this syntax. I also hit this when I upgraded to v5 (and, frankly, just in daily usage) because I'm so used to the standard styled-components API.

I agree with the decision to just have one consistent way to do things (e.g. styled('div')) but it might be worth a bit more consideration (maybe, I'm thinkin' some more calling-out in the docs?) for how deeply ingrained the styled.div-style API is for many people.

Is there some way that we can add the type for things like styled.div that's never (so that no one can accidentally use it) and deprecated, but points people in the right direction that might not be able to immediately figure it out?

[eric-burel]

@dimitropoulos related to my previous comment, I think the question that should be answered first is whether most people should actually use Material UI's styled, since Material UI is a library of component and a design system, but not a technical solution for CSS-in-JS.
It's great that MUI happen to expose their abstracted API. It could be a nice fit if you develop your own library of components for instance, as you would enjoy the same benefits (replace-ability of the underlying styling engine is really something great).

But this abstracted API has been built to develop this library of components, not as a go-to solution for styling anything. Limitation is that it might be simplified compared to a full-fledged engine, and less "safe" as it is not necessarily meant to be used by zillions of developers on a daily basis.

So maybe the right solution, when developing an application that uses Material UI, is to directly use your preferred engine styled function directly, not Material UI abstracted version.

(that's my personal interpretation though, I don't know the Material UI developers intents)

[mnajdova]

@eric-burel does this page on the docs explain a bit more when you may need to use the styled() we expose?

[eric-burel]

Partly yes, this is my understanding currently of the section "What problems does it solve?":

1. It uses Material-UI's default theme if no theme is available in React context.

I think that it could be done by reexporting Emotion/SC styled function but with the right typings/default values. Haven't tried yet.

2. It supports the theme's styleOverrides and variants to be applied, based on the name applied in the options (can be skipped).

Didn't fully grasped the consequences of this. Doesn't it apply only when trying to restyle Material UI components?

3. It adds support for the the sx prop (can be skipped).

Ok, this one is interesting, because it allows to have a unified syntax between Material UI components, and user-defined components with this sx prop.

4. It adds by default shouldForwardProp option that is taking into account all props used internally in the Material-UI components (can be overridden).

Same as 2., I am not 100% sure what it means but it sounds like it's mostly useful when restyling Material UI components, or user-defined components that use Material UI?

I clearly see the improvements from Material UI v4 and this is very exciting!

But now that you use Emotion/Styled Components under the hood, I'd be tempted to look for an alternative approach where you maintain those 4 key points, but using Emotion/Styled Components styled function instead.

I'd be more convinced if you proved that it's not technically possible to enjoy those 4 features by extending Emotion/SC styled somehow, and that using Material UI styled is really the only right way to do this.

[oliviertassinari]

Could we follow up on this discussion in a new GitHub issue? One that focuses on #20012 (comment). It would allow us to keep the scope small, so others can find it and contribute.

[ghost]

Can someone tell me what happened in v5? The old look of the site was amazing but https://next.material-ui.com/ looks terrible to me in terms of "Material" (mostly the component styles but colors do matter too). This is just my opinion and I don't want anyone to be affected by it. Is it simply using a custom theme or have all the styles been changed?

[oliviertassinari]

@sharedrory We are getting rid of this homepage for a new one with the v5 stable release. Please ignore it.
Regarding what happened in v5, we are covering a high-level overview in #27912.

[dkadrios]

I actually like the new doc pages 😀

My only (long standing) complaints revolve around the search feature. If you start typing a component name, then the top result is the API page which is usually what I'm after, but if you finish typing an exact match it goes away. e.g. type "gri" and the Grid API page is top, but type "grid" and poof.

I also wish hitting ENTER would open the top result. I can down-arrow to select and then press enter to open it, but I'm super lazy 🙃

[siriwatknp]

My only (long standing) complaints revolve around the search feature

Thanks for the feedback, I am looking into it. #16502