[material-ui] Replace JS color manipulation with native color syntax #43942

siriwatknp · 2024-09-30T08:04:28Z

Deploy preview

closes #40104
closes #36007
closes #37901
closes #43540
closes #43324
closes #43180
closes #43382
closes #41729
closes #41728

For detailed proposal, check out #43943

For Reviewer

Core Theme System Changes

createPalette.js accept internal colorSpace to mix light, dark, and contrastText with pure CSS.
createThemeNoVars attach color functions to the theme object.
createThemeWithVars.js support a new flag nativeColor through CSS theme variables feature. (internal color space is set to OKLCH for perceptual uniformity)

Component Migrations (30+ components)

All components now use theme.alpha(), theme.lighten() and theme.darken() instead of direct alpha imports for backward compat.

The changes are ensured by the visual regression tests.

Documentation & Interactive Demos

Codemod Implementation

npx @mui/codemod@latest v7.0.0/theme-color-functions <path>

Replace the usage of the alpha, lighten, and darken functions from @mui/system/colorManipulator to use the theme object instead.

- import { alpha, lighten, darken } from '@mui/system/colorManipulator';

- alpha(theme.palette.primary.main, 0.8)
+ theme.alpha((theme.vars || theme).palette.primary.main, 0.8)

- lighten(theme.palette.primary.main, 0.1)
+ theme.lighten(theme.palette.primary.main, 0.1)

- darken(theme.palette.primary.main, 0.3)
+ theme.darken(theme.palette.primary.main, 0.3)

Key Technical Decisions

Why OKLCH as Default Color Space: Provides perceptually uniform color adjustments compared to RGB/HSL
Why Relative Color Syntax: Enables pure CSS contrast calculations without JavaScript runtime overhead
Why color-mix() for Lighten/Darken: More accurate color blending than mathematical transformations
Backward Compatibility: All changes are opt-in via nativeColorSyntax flag, ensuring zero breaking changes

Overview

This PR introduces native CSS color manipulation support through CSS relative colors and color-mix(), eliminating JavaScript-based color calculations when the feature is enabled. The implementation leverages modern CSS color spaces, with OKLCH as the default for perceptually uniform color manipulations, while maintaining full backward compatibility.

What's Changed

✨ Added nativeColorSyntax flag to enable native CSS color features
🎨 Added theme.alpha(), theme.lighten(), and theme.darken() adapter functions for backward compatability.
🔄 Migrated 30+ Material-UI components from using JS color manipulation to theme color functions.
📚 Added comprehensive documentation page and interactive demos
🛠️ Created codemod for automated migration of custom code
🚀 Zero breaking changes - fully opt-in feature

Key Features

🎨 Native CSS Color Manipulation

When nativeColorSyntax is enabled:

OKLCH color space: Automatically selected for relative color calculations
CSS color-mix(): Hardware-accelerated color blending
Alias support: Reference external CSS variables as color values

🔧 Theme Color Manipulators

`theme.alpha(color, coefficient)`

The new alpha function uses relative color to adjust the alpha channel value:

// Standard mode (no CSS variables, no feature)
theme.alpha('#1976d2', 0.5); // → "rgba(25, 118, 210, 0.5)"

// ------------------------------

// When nativeColorSyntax is enabled, the color space is automatically set to `'oklch'` internally

theme.alpha(theme.vars.palette.primary.main, 0.5); // → "oklch(from var(--mui-palette-primary-main) l c h / 0.5)"
theme.alpha(theme.vars.palette.primary.main, '0.5 + 0.3'); // → "oklch(from var(--mui-palette-primary-main) l c h / calc(0.5 + 0.3))"
theme.alpha('oklch(0.65 0.3 28.95)', 0.5); // → "oklch(from oklch(0.65 0.3 28.95) l c h / 0.5)"

`theme.lighten(color, coefficient)` & `theme.darken(color, coefficient)`

These functions use CSS color-mix() when native color syntax is enabled:

// Standard mode - traditional color calculations
theme.lighten('#1976d2', 0.5); // → Traditional lighten calculation result
theme.darken('#1976d2', 0.3); // → Traditional darken calculation result

// ------------------------------

// When nativeColorSyntax is enabled, the color space is automatically set to `'oklch'` internally

theme.lighten('oklch(0.65 0.3 28.95)', 0.5); // → "color-mix(in oklch, oklch(0.65 0.3 28.95), #fff 50%)"
theme.darken('oklch(0.65 0.3 28.95)', 0.3); // → "color-mix(in oklch, oklch(0.65 0.3 28.95), #000 30%)"
theme.lighten(theme.vars.palette.primary.main, 0.3); // → "color-mix(in oklch, oklch(from var(--mui-palette-primary-main) l c h), #fff 30%)"

🌈 Cross-Color Space Compatibility

https://deploy-preview-43942--material-ui.netlify.app/material-ui/customization/css-theme-variables/native-color-syntax/#modern-color-spaces

↖️ Alias external token

https://deploy-preview-43942--material-ui.netlify.app/material-ui/customization/css-theme-variables/native-color-syntax/#aliasing-color-variables

✨ Automatic contrast calculation

Use relative color based on the color-contrast research.

https://deploy-preview-43942--material-ui.netlify.app/material-ui/customization/css-theme-variables/native-color-syntax/#contrast-color-function

Migration Strategy

Added an upgrade guide for users who want to start using native color syntax https://deploy-preview-43942--material-ui.netlify.app/material-ui/migration/upgrade-to-native-color-syntax/

Performance

From a quick benchmark using the blog template comparing between JS color manipulation and Native color syntax, there is no significant difference in terms of runtime performance.

I have followed (at least) the PR section of the contributing guide.

mui-bot · 2024-09-30T08:07:18Z

Netlify deploy preview

Bundle size report

Bundle	Parsed Size	Gzip Size
@mui/material	▼-1.67KB^(-0.32%)	🔺+368B^(+0.24%)
@mui/lab	🔺+1.7KB^(+1.28%)	🔺+657B^(+1.62%)
@mui/system	🔺+203B^(+0.29%)	🔺+87B^(+0.35%)
@mui/utils	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Generated by 🚫 dangerJS against 5f0450e

…olor-mix

siriwatknp · 2025-07-21T03:31:52Z

What about nativeColor

Sounds good to me.

I think it would be good to add a visual example of the differences so users can make a better decision. Otherwise they won't know how different the colors are.

I'll find some color examples

Besides that, there are two minor bugs on dark mode on the docs:

The first one looks correct to me, the colors are static. It should not change.
The second one is fixed.

docs/data/material/customization/css-theme-variables/native-color.md

docs/data/material/migration/upgrade-to-v7/upgrade-to-native-color.md

Co-authored-by: mapache-salvaje <71297412+mapache-salvaje@users.noreply.github.com> Signed-off-by: Siriwat K <siriwatkunaporn@gmail.com>

DiegoAndai · 2025-07-23T16:10:56Z

The first one looks correct to me

I was referencing the text to the side of the boxes, it's unreadable 😅

siriwatknp · 2025-07-24T02:58:16Z

I was referencing the text to the side of the boxes, it's unreadable 😅

Nice catch! fixed.

siriwatknp · 2025-07-28T07:54:53Z

@DiegoAndai I added the color difference example to https://deploy-preview-43942--material-ui.netlify.app/material-ui/customization/css-theme-variables/native-color/#caveats

DiegoAndai · 2025-07-28T19:19:30Z

Thanks @siriwatknp. I think we should use the primary color for the default color shown:

docs/data/material/customization/css-theme-variables/ThemeColorFunctions.js

packages/mui-material/src/Chip/Chip.js

packages/mui-material/src/Link/Link.js

siriwatknp · 2025-07-29T02:51:11Z

Thanks @siriwatknp. I think we should use the primary color for the default color shown:

The primary color has no different. I think the point of the demo is to show a color that produces different result at first glance. For the default colors of Material UI, there is no difference. That's why I put this information in the caveat.

DiegoAndai · 2025-07-30T18:30:34Z

The primary color has no different.

I'm not sure we should optimize for showing the most changed color either. The one we have now has different text color, which sure, showcases the differences, but most colors are very similar. In the end, we want to reassure users that even though there's a difference, it's minimal. Picking the color with most difference is not a good strategy for that message.

siriwatknp · 2025-07-31T04:23:48Z

I'm not sure we should optimize for showing the most changed color either. The one we have now has different text color, which sure, showcases the differences, but most colors are very similar. In the end, we want to reassure users that even though there's a difference, it's minimal. Picking the color with most difference is not a good strategy for that message.

Then, should I remove the demo instead and proceed with the PR? It's minor so might be better to wait until users start using this feature.

siriwatknp · 2025-08-01T01:53:47Z

Then, should I remove the demo instead and proceed with the PR? It's minor so might be better to wait until users start using this feature.

@mapache-salvaje Any thought about the caveat demo?

DiegoAndai

@siriwatknp I agree, the demo is not important enough to block the feature. Good to go on my side.

poc color-mix

bb3d4e3

siriwatknp added package: material-ui labels Sep 30, 2024

siriwatknp marked this pull request as draft September 30, 2024 08:04

siriwatknp added 4 commits October 1, 2024 16:08

Merge branch 'master' of https://github.com/mui/material-ui into v6/c…

8d5fc48

…olor-mix

migrate to theme.alpha

ffb02e0

migrate lighten and darken

e942c7f

add color space selector

3fb44a7

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Oct 9, 2024

Merge branch 'master' of https://github.com/mui/material-ui into v6/c…

c840088

…olor-mix

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Oct 21, 2024

github-actions bot added PR: out-of-date The pull request has merge conflicts and can't be merged. and removed PR: out-of-date The pull request has merge conflicts and can't be merged. labels Nov 14, 2024

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jan 13, 2025

siriwatknp added 3 commits April 28, 2025 14:45

Merge branch 'master' of https://github.com/mui/material-ui into v6/c…

babe7a3

…olor-mix

fix conflict

6faefb5

fix color space

5441c8d

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Apr 28, 2025

add color space value for getContrastText

0a7d074

siriwatknp mentioned this pull request Apr 28, 2025

[colorManipulator] lighten/darken a CSS var() color #43324

Closed

siriwatknp added 9 commits April 30, 2025 09:01

Merge branch 'master' of https://github.com/mui/material-ui into v6/c…

e0c5e42

…olor-mix

fix snackbar

aa78cdd

add colorSpace to createPalette

5671a40

wip

007718c

fix missing arg

bf1f17e

update demo

11e6a51

fix color space param

4db2d95

move attachColorManipulators to createThemeNoVars

30307d9

fix regex

740ba24

siriwatknp added 3 commits July 21, 2025 10:18

Merge branch 'master' of github.com:mui/material-ui into v6/color-mix

aefc8ef

fix demo on dark mode

5bb3709

rename to native color

de4ed0a

fix lint

d23382e

siriwatknp requested a review from mapache-salvaje July 21, 2025 06:48

mapache-salvaje reviewed Jul 21, 2025

View reviewed changes

Apply suggestions from code review

4e31546

Co-authored-by: mapache-salvaje <71297412+mapache-salvaje@users.noreply.github.com> Signed-off-by: Siriwat K <siriwatkunaporn@gmail.com>

siriwatknp added 2 commits July 24, 2025 09:36

Merge branch 'master' of github.com:mui/material-ui into v6/color-mix

01524e1

fix demo

2f15187

siriwatknp requested review from DiegoAndai and mapache-salvaje July 24, 2025 02:58

siriwatknp added 3 commits July 28, 2025 13:03

Merge branch 'master' of github.com:mui/material-ui into v6/color-mix

68e6b5e

add contrast comparision demo

f78b3d1

docs ts format

a10e381

DiegoAndai reviewed Jul 28, 2025

View reviewed changes

docs/data/material/customization/css-theme-variables/ThemeColorFunctions.js Show resolved Hide resolved

packages/mui-material/src/Chip/Chip.js Show resolved Hide resolved

packages/mui-material/src/Link/Link.js Show resolved Hide resolved

siriwatknp requested a review from DiegoAndai July 29, 2025 02:37

DiegoAndai approved these changes Aug 1, 2025

View reviewed changes

siriwatknp added 2 commits August 4, 2025 09:03

remove unimportant demo

4acea27

Merge branch 'master' of github.com:mui/material-ui into v6/color-mix

5f0450e

siriwatknp merged commit 83bfdd7 into mui:master Aug 4, 2025
22 checks passed

cmdcolin mentioned this pull request Aug 6, 2025

Adds support for prefers-color-scheme GMOD/jbrowse-components#4380

Closed

Uh oh!

[material-ui] Replace JS color manipulation with native color syntax #43942

[material-ui] Replace JS color manipulation with native color syntax #43942

Uh oh!

Conversation

siriwatknp commented Sep 30, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

For Reviewer

Core Theme System Changes

Component Migrations (30+ components)

Documentation & Interactive Demos

Codemod Implementation

Key Technical Decisions

Overview

What's Changed

Key Features

🎨 Native CSS Color Manipulation

🔧 Theme Color Manipulators

theme.alpha(color, coefficient)

theme.lighten(color, coefficient) & theme.darken(color, coefficient)

🌈 Cross-Color Space Compatibility

↖️ Alias external token

✨ Automatic contrast calculation

Migration Strategy

Performance

Uh oh!

mui-bot commented Sep 30, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Netlify deploy preview

Bundle size report

Uh oh!

siriwatknp commented Jul 21, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DiegoAndai commented Jul 23, 2025

Uh oh!

siriwatknp commented Jul 24, 2025

Uh oh!

siriwatknp commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DiegoAndai commented Jul 28, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

siriwatknp commented Jul 29, 2025

Uh oh!

DiegoAndai commented Jul 30, 2025

Uh oh!

siriwatknp commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

siriwatknp commented Aug 1, 2025

Uh oh!

DiegoAndai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

siriwatknp commented Sep 30, 2024 •

edited

Loading

`theme.alpha(color, coefficient)`

`theme.lighten(color, coefficient)` & `theme.darken(color, coefficient)`

mui-bot commented Sep 30, 2024 •

edited

Loading

siriwatknp commented Jul 28, 2025 •

edited

Loading

siriwatknp commented Jul 31, 2025 •

edited

Loading