Migrate Material UI components to support theme CSS variables #32049

mnajdova · 2022-03-30T07:05:34Z

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 #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

Pick a component in the “Ready to be picked up” section
Read the “Patterns” section
Replace the use of these theme tokens to (theme.vars || theme).*.
- theme.palette.*
- theme.shape.borderRadius
- theme.shadows
- theme.zIndex
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.
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.
Open a PR and put the URL to the the end of the component below (so that everyone knows it has been taken)
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!

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: #32049 (comment)

The text was updated successfully, but these errors were encountered:

vicasas · 2022-04-28T17:45:48Z

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

siriwatknp · 2022-04-29T05:44:22Z

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.

ZeeshanTamboli · 2022-04-29T06:43:42Z

Replace the use of these theme tokens to (theme.vars || theme)..
theme.palette.
theme.shape.borderRadius
theme.typography.fontFamily
theme.typography.fontSize
theme.typography.fontWeightLight
theme.typography.fontWeightRegular
theme.typography.fontWeightMedium
theme.typography.fontWeightBold
theme.typography.htmlFontSize
theme.shadows
theme.zIndex

Correct me if I am wrong, but I think theme.typography should not be updated as per the following theme structure for CSS
variables:

import { Theme as MuiTheme } from '@mui/material/styles';

declare module '@mui/material/styles' {
  interface Theme {
    vars: Omit<
      MuiTheme,
      'typography' | 'mixins' | 'breakpoints' | 'direction' | 'transitions'
    >;
  }
}

siriwatknp · 2022-04-29T06:51:35Z

@ZeeshanTamboli

You are right. Even though, I think some part of the typography is nice to have to be generated as CSS variables but let's do thing one step at a time and neglect the typography for now. I have updated the issue decription.

alippai · 2022-05-25T03:36:56Z

It might be early to ask, but do you plan to keep both solutions, add this as an alternative only or will you replace the current provider with the new one eventually?

siriwatknp · 2022-05-25T08:46:14Z

do you plan to keep both solutions

Absolutely, yes. The CSS variables support is considered a new feature that developers can opt-in. We don't plan to replace the current one at this point.

siriwatknp · 2022-06-17T06:38:02Z

👋 Progress Updates

Migration

The migration to support CSS variables in all components is at the finishing line. All issues have been resolved and we can fix all the problems that cause dark mode flicker when you adopt the new provider.

Typescript

We will provide a module augmentation file similar to the lab to augment the theme to have access to the CSS variables. You just need one line in your project.

import type {} from '@mui/material/themeCssVarsAugmentation';

// You will be able to see `theme.vars` in all of the APIs eg. styled, sx, useTheme

This should work as well if you have custom module augmentation.

Docs

After the migration and the types are done, we will start working on the docs about how to work with CSS variables. There are mental model changes that are different but we believe that it is the right way to go

For example:

// current
color: theme.palette.mode === 'dark' ? theme.palette.primary.main : theme.palette.text.primary,

// With CSS variables
color: theme.palette.primary.main,
[theme.getColorSchemeSelector('dark')]: {
  color: theme.palette.text.primary,
}

Using JS condition to switch between colors at runtime will not scale:

causes dark mode flickers (or flashing)
will be complicated if you have more than light and dark color schemes.
for a very big application, it is not performant because all the styles are recalculated when the mode changes.

Blog post

We will definitely share insights and overviews about what it means for Material UI to adopt CSS variables!

ceopaludetto · 2022-06-21T02:24:37Z

I've been testing this new provider, works great, but I have a doubt. I wanna use prefers-color-scheme media query instead of script-managed value injected in html, how can I do that?

After reading createCssVarsProvider code, I think we can leave a option like tailwind does(https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually), I propose something like attributeManagedStyles: boolean or mediaManagedStyles: boolean. If user toggle on, we add the global style like this:

:root {
    --md-some-color: ;
}

@media (prefers-color-scheme: dark) {
    :root {
        --md-some-color: ;
    }
}

And we change getColorSchemeSelector util to:

(target: 'dark' | 'light') => `(prefers-color-scheme: ${target})`

What do you think?

siriwatknp · 2022-06-21T07:10:06Z

@ceopaludetto Thanks for the feedback. Can you explain a bit more about your use case? Providing a minimal CodeSandbox would be great!

ceopaludetto · 2022-06-21T23:20:41Z

@ceopaludetto Thanks for the feedback. Can you explain a bit more about your use case? Providing a minimal CodeSandbox would be great!

@siriwatknp
So, my idea is to provide a prop in CssVarsProvider which changes the css var injection in :root. If user chooses "data-attribute", the injection will be:

:root {
  --md-some-color: 255 255 255;
}

[data-theme="dark"] {
    :root {
        --md-some-color: 0 0 0;
    }
}

But if he chooses "media", the injection will be:

:root {
  --md-some-color: 255 255 255;
}

@media(prefers-color-scheme: dark) {
    :root {
        --md-some-color: 0 0 0;
    }
}

In second option, user loss the ability to dynamic change the theme based on preference inside the application, but he can use without calling getInitColorSchemeScript and website color will always match system preference

I've created two sandboxes, one with data-attribute behavior and another with media behavior, I've used emotion for example purposes, but I tried to replicate CssVarsProvider actual implementation.

data-attribute: https://codesandbox.io/s/emotion-data-attribute-rw288w
media: https://codesandbox.io/s/emotion-data-media-qw25y3

siriwatknp · 2022-06-22T01:01:52Z

But if he chooses "media", the injection will be:

@ceopaludetto Got it, yeah it is not possible at this point. Would you mind creating a new issue to discuss further?

ceopaludetto · 2022-06-22T03:17:15Z

But if he chooses "media", the injection will be:

@ceopaludetto Got it, yeah it is not possible at this point. Would you mind creating a new issue to discuss further?

Of course not, thanks for listening, i'll open later

TimoWilhelm · 2022-06-24T13:24:04Z

@siriwatknp This look great! I think there might be an issue with the SnackbarContent.

https://github.com/mui/material-ui/pull/32835/files#diff-c69c0067f63247670034da3fc1b223b7603fc9cee0545d1ce2cf1521e58fbebbR33-R35

The content color will always be primary text color, which will have poor contrast with the snackbar background color.

I think it should be something like color: theme.vars.palette[theme.vars.palette.SnackbarContent.bg].contrastTextChannel, but I don't think there is an contrastTextChannel for --mui-palette-SnackbarContent-bg yet.

Rafcin · 2022-06-25T21:11:42Z

Even though Experimental_CssVarsProvider says experimental, is it stable enough to use? I've been playing around with it in sandboxes and it's hands down my new favorite feature.

Also a question regarding the vars provider. Suppose we have a theme object, until this point had my own version of useColorScheme and my theme object had my palettes split into dark and light. With the experimental vars, should the theme now be changed to use colorSchemes: { light: { palette {...} }, dark: { palette: {...} } } or do we still need to keep palette in the root of the theme?

siriwatknp · 2022-07-04T01:14:23Z

Even though Experimental_CssVarsProvider says experimental, is it stable enough to use? I've been playing around with it in sandboxes and it's hands down my new favorite feature.

Good to hear that! I believe that the CssVarsProvider is quite stable and there is no major change that I can think of.

With the experimental vars, should the theme now be changed to use colorSchemes

Yes, colorSchemes must be used with CssVarsProvider. (A pile of documentation will be added soon)

Before:

const theme = createTheme({ palette: { mode: userSelectedMode } });

<ThemeProvider theme={theme}>

After:

const theme = extendTheme({
  colorSchemes: {
    light: { palette: { ... } },
    dark: { palette: { ... } },
  }
});

<CssVarsProvider theme={theme}>

Note: CssVarsProvider is built on top of ThemeProvider with the feature that generates CSS variables from the theme.

I think this diagram describes it really well (more details in #27651).

maks-yaremishyn · 2022-07-13T09:15:39Z

Hey, @TimoWilhelm and mui team! We consume mui library and have rather straightforward use of snackbar component

      <Snackbar
        open={!!successMessage}
        onClose={...}
        autoHideDuration={5000}
        anchorOrigin={{
          vertical: 'bottom',
          horizontal: 'left',
        }}
      >
        <Alert severity="success">
          {successMessage}
        </Alert>
      </Snackbar>

after dependencies update unexpectedly text or success messages changed from white to black. is such side effect possible as result of this PR ?

TimoWilhelm · 2022-07-13T10:08:26Z

@maks-yaremishyn The Alert component color should not be affected by the Snackbar variables. For me, it's using the correct color (rgb(30, 70, 32) in light mode) for the standard variant inside a Snackbar. Do you have images for before and after?

maks-yaremishyn · 2022-07-13T10:16:45Z

TimoWilhelm · 2022-07-13T10:25:31Z

This looks like you have custom styling applied to your Alert.

To answer your question: No, the PR should not affect the Alert component since it has it's own styling properties by default. If you override the styles to inherit the color property from the Snackbar, then I guess it could happen.

mwskwong · 2022-07-22T09:39:34Z

A few questions, if anyone is kind enough to answer these

Is this new CSS variable API intended to replace the existing theme API eventually?
Let's say I just need light mode. By omitting the dark key in experimental_extendTheme, will that prevent the default dark mode styles from being bundled into the PROD build?

siriwatknp · 2022-07-25T03:10:03Z

@mwskwong Great questions!

Is this new CSS variable API intended to replace the existing theme API eventually?

For Material UI, NO. We consider CSS variables support as an opt-in feature on top of the default API.

Let's say I just need light mode. By omitting the dark key in experimental_extendTheme, will that prevent the default dark mode styles from being bundled into the PROD build?

No, omitting the key does not remove the default dark mode styles (that's why it is the default styles). The workaround is to remove the dark key from the theme object directly before passing it to CssVarsProvider.

const theme = extendTheme();

delete theme.colorSchemes.dark;

// CssVarsProvider will generate CSS variables based on the object in `theme.colorSchemes`.
<CssVarsProvider theme={theme}>

Proof that it works: https://codesandbox.io/s/cssvariablescustomization-demo-material-ui-forked-qfy955?file=/demo.js

I will put this in the docs. #33417

mwskwong · 2022-08-17T02:13:33Z

I noticed the migration task doesn't include lab components. Is that intended to be included some time in the future?

siriwatknp · 2022-08-17T08:18:42Z

I noticed the migration task doesn't include lab components. Is that intended to be included some time in the future?

Sure! I have created an umbrella issue to keep track of it. The contribution from the community is welcome as well.

ZeeshanTamboli · 2022-08-22T06:40:20Z

I noticed the migration task doesn't include lab components. Is that intended to be included some time in the future?

@mwskwong We have added support for CSS variables in lab components. It should be available in the next release.

mnajdova added the status: waiting for maintainer These issues haven't been looked at yet by a maintainer label Mar 30, 2022

danilo-leal added package: material-ui Specific to @mui/material and removed status: waiting for maintainer These issues haven't been looked at yet by a maintainer labels Mar 30, 2022

siriwatknp changed the title ~~Migrate all components to CSS variables~~ Migrate all components to support theme CSS variables Apr 2, 2022

siriwatknp changed the title ~~Migrate all components to support theme CSS variables~~ Migrate Material UI components to support theme CSS variables Apr 2, 2022

ivan-ngchakming mentioned this issue Apr 3, 2022

[Input] Support CSS variables #32128

Merged

1 task

danilo-leal added the umbrella For grouping multiple issues to provide a holistic view label Apr 4, 2022

mnajdova added this to Q2 2022 Apr - Jun in MUI Core public roadmap Apr 15, 2022

This was referenced Apr 28, 2022

[ButtonGroup] Add support for CSS variables #32498

Merged

[Avatar] Add support for CSS variables #32499

Merged

siriwatknp pinned this issue Apr 29, 2022

siriwatknp mentioned this issue Apr 29, 2022

[experiment] Add template for testing Material UI components with CSS variables #32500

Merged

1 task

This was referenced Apr 29, 2022

[AvatarGroup] Add support for CSS variables #32507

Merged

[Badge] Add support for CSS variables #32516

Merged

[BottomNavigation] Add support for CSS variables #32517

Merged

[Divider] Add support for CSS variables #32519

Merged

This was referenced May 2, 2022

[Accordion] Add support for CSS variables #32542

Merged

[CircularProgress] Add support for CSS variables #32543

Merged

[Tabs] Add support for CSS variables #32547

Merged

This was referenced May 2, 2022

[CardActionArea] Add support for CSS variables #32554

Merged

[Dialog] Add support for CSS variables #32555

Merged

[Rating] Add support for CSS variables #32556

Merged

nghiamvt mentioned this issue May 2, 2022

[MenuItem] Add support for CSS variables #32561

Merged

1 task

alisasanib mentioned this issue May 2, 2022

[Fab] Add support for CSS variables #32564

Merged

1 task

nghiamvt mentioned this issue May 2, 2022

[Drawer] Add support for CSS variables #32565

Merged

1 task

diggis00 mentioned this issue May 3, 2022

[Paper] Add support for CSS variables #32570

Merged

1 task

winderica mentioned this issue Jun 5, 2022

[Link] Add support for CSS variables #33036

Merged

1 task

aprendendofelipe mentioned this issue Jun 5, 2022

feat(dark-mode): adiciona suporte ao dark mode filipedeschamps/tabnews.com.br#377

Closed

siriwatknp closed this as completed Jun 23, 2022

TimoWilhelm mentioned this issue Jun 24, 2022

[SnackbarContent] fix message text color with css var provider #33285

Merged

1 task

siriwatknp unpinned this issue Aug 1, 2022

siriwatknp mentioned this issue Aug 17, 2022

Migrate lab components to support theme CSS variables #33959

Closed

4 tasks

This was referenced Nov 1, 2022

[NativeSelectInput] Support CSS theme variables #34975

Merged

Support CSS theme variables in DataGrid and DatePickers mui/mui-x#6702

Closed

koolskateguy89 mentioned this issue Jan 1, 2023

Use MUI lborocs/22cob290-part2-team-10#40

Closed

15 tasks

quanganh2001 mentioned this issue Apr 7, 2024

Dark Mode and Light Mode sync with System part 1 quanganh2001/trello-web#7

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate Material UI components to support theme CSS variables #32049

Migrate Material UI components to support theme CSS variables #32049

mnajdova commented Mar 30, 2022 •

edited by siriwatknp

vicasas commented Apr 28, 2022

siriwatknp commented Apr 29, 2022

ZeeshanTamboli commented Apr 29, 2022

siriwatknp commented Apr 29, 2022 •

edited

alippai commented May 25, 2022

siriwatknp commented May 25, 2022

siriwatknp commented Jun 17, 2022 •

edited

ceopaludetto commented Jun 21, 2022

siriwatknp commented Jun 21, 2022

ceopaludetto commented Jun 21, 2022 •

edited

siriwatknp commented Jun 22, 2022 •

edited

ceopaludetto commented Jun 22, 2022

TimoWilhelm commented Jun 24, 2022 •

edited

Rafcin commented Jun 25, 2022

siriwatknp commented Jul 4, 2022 •

edited

maks-yaremishyn commented Jul 13, 2022

TimoWilhelm commented Jul 13, 2022

maks-yaremishyn commented Jul 13, 2022

TimoWilhelm commented Jul 13, 2022

mwskwong commented Jul 22, 2022 •

edited

siriwatknp commented Jul 25, 2022 •

edited

mwskwong commented Aug 17, 2022 •

edited

siriwatknp commented Aug 17, 2022 •

edited

ZeeshanTamboli commented Aug 22, 2022

Migrate Material UI components to support theme CSS variables #32049

Migrate Material UI components to support theme CSS variables #32049

Comments

mnajdova commented Mar 30, 2022 • edited by siriwatknp

We need your help!

Contribution guides

Patterns

List of components

Ready to be picked up

Need clarification

vicasas commented Apr 28, 2022

siriwatknp commented Apr 29, 2022

ZeeshanTamboli commented Apr 29, 2022

siriwatknp commented Apr 29, 2022 • edited

alippai commented May 25, 2022

siriwatknp commented May 25, 2022

siriwatknp commented Jun 17, 2022 • edited

👋 Progress Updates

Migration

Typescript

Docs

Blog post

ceopaludetto commented Jun 21, 2022

siriwatknp commented Jun 21, 2022

ceopaludetto commented Jun 21, 2022 • edited

siriwatknp commented Jun 22, 2022 • edited

ceopaludetto commented Jun 22, 2022

TimoWilhelm commented Jun 24, 2022 • edited

Rafcin commented Jun 25, 2022

siriwatknp commented Jul 4, 2022 • edited

maks-yaremishyn commented Jul 13, 2022

TimoWilhelm commented Jul 13, 2022

maks-yaremishyn commented Jul 13, 2022

TimoWilhelm commented Jul 13, 2022

mwskwong commented Jul 22, 2022 • edited

siriwatknp commented Jul 25, 2022 • edited

mwskwong commented Aug 17, 2022 • edited

siriwatknp commented Aug 17, 2022 • edited

ZeeshanTamboli commented Aug 22, 2022

mnajdova commented Mar 30, 2022 •

edited by siriwatknp

siriwatknp commented Apr 29, 2022 •

edited

siriwatknp commented Jun 17, 2022 •

edited

ceopaludetto commented Jun 21, 2022 •

edited

siriwatknp commented Jun 22, 2022 •

edited

TimoWilhelm commented Jun 24, 2022 •

edited

siriwatknp commented Jul 4, 2022 •

edited

mwskwong commented Jul 22, 2022 •

edited

siriwatknp commented Jul 25, 2022 •

edited

mwskwong commented Aug 17, 2022 •

edited

siriwatknp commented Aug 17, 2022 •

edited