Migrate Material UI components to support theme CSS variables

We need your help!

Starting from 5.6.0 we are adding a new experimental API for supporting CSS variables in the Material UI components. You can see more details for this new feature on https://github.com/mui/material-ui/issues/27651 or our docs page.

The changes are not breaking so we can safely apply them in the components during the lifecycle of v5.

Initially, the idea was implemented in one component, the Button, but we would need this to be applied to all components. This issue will help track the progress of the migration.

Contribution guides

1. Pick a component in the “Ready to be picked up” section
2. Read the “Patterns” section
3. Replace the use of these theme tokens to (theme.vars || theme).*.
   • theme.palette.*
   • theme.shape.borderRadius
   • theme.shadows
   • theme.zIndex
4. Create a new page using the template at docs/pages/experiments/material-ui/css-vars-template.tsx. Ex. if you pick Accordion component, create the page (docs/pages/experiments/material-ui/accordion.tsx) and copy the template. Then, import the Accordion and render it on the page.
5. Verify that it works
   1. Run yarn docs:dev
   2. go to URL /experiments/material-ui/{component}/ and check the component (it should look the same)
   3. Open the DevTool and toggle the dark mode button at the top of the page, the classNames of the component should not change.
6. Open a PR and put the URL to the the end of the component below (so that everyone knows it has been taken)
7. Tag @mui/core to review

If you come across any issue or are unsure of the changes, feel free to open a PR and describe the problem + tag @mui/core for help.

Patterns

Straightforward

- borderRadius: theme.shape.borderRadius
+ borderRadius: (theme.vars || theme).shape.borderRadius

- border: `1px solid ${theme.palette.action.disabledBackground}`,
+ border: `1px solid ${(theme.vars || theme).palette.action.disabledBackground}`,

color manipulation

Some components are using a conditional statement to switch values between modes which causes the flicker issue for SSR application. To fix this, we have provided channel colors to be combined with opacity (thanks to CSS variables, this seems to be the only solution so far).

The channel colors in the theme palettes are mainChannel, lightChannel, darkChannel and contrastTextChannel.

- backgroundColor: alpha(theme.palette.primary.main, theme.palette.action.selectedOpacity),
+ backgroundColor: theme.vars ?
+   `rgba(${theme.vars.palette.primary.mainChannel} / ${theme.vars.palette.action.selectedOpacity})` :
+   alpha(theme.palette.primary.main, theme.palette.action.selectedOpacity),

- backgroundColor: alpha(
-       theme.palette.primary.main,
-       theme.palette.action.selectedOpacity + theme.palette.action.focusOpacity,
-     ),
+ backgroundColor: theme.vars ?
+       `rgba(${theme.vars.palette.primary.mainChannel} / calc(${theme.vars.palette.action.selectedOpacity} + ${theme.vars.palette.action.focusOpacity}))` :
+       alpha(...)

List of components

Ready to be picked up

✅ First set is done!

• Accordion #32542
• AvatarGroup #32507
• Autocomplete #32598
• Badge #32516
• BottomNavigation #32517
• BottomNavigationAction #32517
• Button https://github.com/mui/material-ui/pull/31138
• CardActionArea #32554
• CircularProgress #32543
• CssBaseline #32618
• DialogContent #32555
• Divider #32519
• Drawer #32565
• Fab #32564
• FormControlLabel #32588
• FormHelperText #32596
• FormLabel #32602
• Icon #32595
• IconButton #32590
• ImageListItemBar #32578
• InputAdornment #32607
• ListItem https://github.com/mui/material-ui/pull/32580
• ListItemButton #32582
• ListItemIcon #32583
• ListSubheader #32584
• MenuItem #32561
• MobileStepper #32606
• Modal #32605
• ~[ ] Pagination~
• PaginationItem #32612
• Rating #32556
• ~[ ] ScopedCssBaseline~
• Snackbar #32603
• SpeedDial #32613
• StepIcon #32609
• StepLabel #32609
• SvgIcon #32610
• Tab #32547
• Table #32614
• TablePagination #32615
• TableRow #32614
• TableSortLabel #32616
• Tabs #32547
• ToggleButton #32600
• ToggleButtonGroup https://github.com/mui/material-ui/pull/32617
• Tooltip #32594

Need clarification

These components contain hardcoded values between modes. We will put the guidelines for each of these components and moved them to “Ready to be picked up”.

Proposal: https://github.com/mui/material-ui/issues/32049#issuecomment-1124601805

• Alert https://github.com/mui/material-ui/pull/32624
• AppBar https://github.com/mui/material-ui/pull/32835
• Avatar https://github.com/mui/material-ui/pull/32499
• ButtonGroup https://github.com/mui/material-ui/pull/32498
• Chip https://github.com/mui/material-ui/pull/32835
• Checkbox #32579
• FilledInput https://github.com/mui/material-ui/pull/32835
• Input https://github.com/mui/material-ui/pull/32128
  • InputBase
• LinearProgress https://github.com/mui/material-ui/pull/32835
• OutlinedInput https://github.com/mui/material-ui/pull/32835
• Paper #32570
• Radio #32599
• SpeedDialAction #32608
• Skeleton https://github.com/mui/material-ui/pull/32835
• Slider https://github.com/mui/material-ui/pull/32835
• SnackbarContent https://github.com/mui/material-ui/pull/32835
• StepConnector https://github.com/mui/material-ui/pull/32835
• StepContent https://github.com/mui/material-ui/pull/32835
• Switch https://github.com/mui/material-ui/pull/32835
• TableCell https://github.com/mui/material-ui/pull/32835

[siriwatknp]

Could we suppose that for components that don’t use theme we could mark them as don’t take? For example List component.

I have updated the list.

[vicasas]

Could we suppose that for components that don’t use theme we could mark them as don’t take? For example List component.