[HOLD] Pigment CSS: RFC discussion

[brijeshb42]

Continuing the discussion from the RFC issue started in #38137

cc: @o-alexandrov @nmn @oliviertassinari @mnajdova @layershifter

[DarrenBaldwin07]

Are there plans to make this zero runtime solution agnostic from MUI? Would be great to be able to build on this solution in other component libs as well

[mnajdova]

Yes, this is the plan and how it is current designed.

[oliviertassinari]

There was also discussion on making it agnostic to React.

[Axe1200]

I hope so too

[aeischeid]

I would love for some solution that works well with CSS modules which is available in both Next.js and Astro, (I think this probably means css vars?) The current theme and runtime styling solution really makes MUI in Astro sort of a non-starter too, so just tossing it out there to keep that framework in mind.

[mnajdova]

This is a great point. We can look into creating an example project and show how it can work.

[Axe1200]

Super

[acomanescu]

Could you, please, clarify if MUI team already decided to use zero-runtime package and discussion about StyleX are just to point out the differences? At this moment, the direction of this thread is not clear enough.

[brijeshb42]

Yes. We are already moving ahead with zero-runtime. No stylex usage, atleast in @mui/material.

[acomanescu]

Thank you for the clarification! We should avoid getting back to pros and cons to keep this focused on the actual scope.

[Axe1200]

Thank you, I understand too

[necolas]

FWIW, StyleX isn't "zero runtime". Having no runtime at all is not practical for atomic CSS libraries, as a runtime is needed to perform merging of styles during composition to avoid the kind of style conflicts that are common when using libraries like Tailwind. The runtime we use for StyleX is called styleQ - it's small, fast, and flexible enough to be used with any compiler not just StyleX. Although the repo has independent benchmarks, we also tested it on facebook.com where the runtime is called 15K times on the feed screen - it took 15ms and was 5x faster than the runtime we were using before. It's very easy to introduce slow paths in a runtime if you're not benchmarking after every change.

[Axe1200]

Thanks for the explanation! Interestingly, even with 15K calls on the runtime page, it only works 15ms. Have you noticed any features when scaling to larger components or when using style compositions more complex?

[bestickley]

Excited for zero runtime! How can I write MUI system style code today that will be compatible with the new zero runtime? Will both of the below flavors be supported?

<Button sx={{ mb: 3 }}>
// or
<Box mb={3}>

[oliviertassinari]

I think the dream would be:

1. to support the sx prop on any component, host element too (span, h1, etc.)
2. to trend toward removing the Box primitive, since 1. covers the same use case. It might take a while though, because removing Box should probably only happen after emotion is no longer a runtime, which could never happen.

[Axe1200]

Yes, the idea with sx on any component really makes Box less needed. I wonder how you see the transition from Box to this approach for large code bases – will there be any migration tools when emotions stop being runtime?

[erwan-joly]

Excited for this as emotion js still doesn't support streaming server side rendering :/ emotion-js/emotion#2800

[Axe1200]

Yes, it's really expected! 😅 I hope that with this change streaming SSR will become real without big crutches.

[aarjithn]

Hi Team, Are there any plans to support an easy migration from v4 makeStyles API?

It seems to have fairly decent usage still

[aarjithn]

Looks like what we basically need is a method that takes in a nested object and returns an object of classnames:

MUI v4:

const useStyles = makeStyles((theme) => ({
  title: {
    color: theme.palette.primary.main,
  }
}));

function App() {
  const classes = useStyles();
  return <div className={classes.title}>I am invisible</div>;
}

Pigment css API:

const title = css(({ theme }) => ({
  color: theme.colors.primary,
  fontSize: theme.spacing.unit * 4,
  fontFamily: theme.typography.fontFamily,
}));

function App() {
  return <div className={title}>I am invisible</div>;
}

Proposed new "makestyles"

const styles = makeStyles(({theme}) => ({
 title: {
   color: theme.colors.primary
 }
}))

function App() {
  return <div className={styles.title}>I am invisible</div>;
}

There could be some minor differences like if response can be used directly without hook as in v4, but still it should be mostly easy to migrate @brijeshb42 what do you think?

[oliviertassinari]

Thee is no plan to support the makeStyles API today. Until we can demonstrate that Pigment CSS works, this looks like a distraction. JSS continues to work.

[Axe1200]

Of course, thanks for the explanation. It is logical to first prove that Pigment CSS works stably before considering makeStyles.

[bestickley]

Hey @brijeshb42, I tried out the recently released @pigment-css/react in my Next.js app and got the error: Error: @pigment-css/react: You were trying to call "css" function without configuring your bundler.

I'm wondering if it has to do with me using turbopack. Will the Next.js plugin support turbopack?

Note, I'm wrapping my nextConfig with withPigment from @pigment-css/nextjs-plugin which is what the error seems to suggest I'm not doing. If you'd like me to create a formal issue I can, I just know this is still very new and it may not be ready yet. Just wanted to clarify on turbopack. Thanks!

[brijeshb42]

Let's move this to a separate issue.

[brijeshb42]

Pigment works by injecting a Webpack plugin into the next config. So as of right now, we won't be able to support turbo till it's atleast not experimental or it exposes a way to have plugins.

[oliviertassinari]

We might want to create an issue for this, it looks equivalent to facebook/stylex#63.

[bestickley]

@brijeshb42, issue created: https://github.com/mui/material-ui/issues/41449
@oliviertassinari, I don't think these issues are equivalent. That issue looks like it's regarding Turborepo, not Turbopack. Turborepo and Turbopack are in the same repo and related though.

[Axe1200]

Understood, thanks for the explanation! Then it is logical that Turbo support is postponed until there is a stable way to add plugins.

[igortas]

How to start adapting MUI 5 components towards pigment zero runtime. Any migration guide?

[stunaz]

I think, mui v6 is on the way for that

[Axe1200]

There is no official guide for migrating MUI 5 to Pigment zero runtime yet, but it is logical to start with the components that are least dependent on JSS or makeStyles. Then gradually replace the styles with Pigment CSS via sx or styled API.

[paulm17]

After all the discussion from the issue mentioned in OP.

I see no mention of atomic styles in the readme. Is this intended for a future release or something that has been dismissed?

Thanks!

[paulm17]

Could you expand on what would be the value of the style prop ? Any arbitrary example works?

Please understand that I'm coming from this as a layman. I don't understand the inner workings of these new css libraries.

The value proposition would be that the inital css is overwritten by a prop.

A quick example would be something like:

import { css, prop } from "@pigment-css/react";
import { CSSProperties } from "react";

const baseStyles = css({
  color: "red",
  background: "white",
  fontWeight: "normal", 
});

interface customComponentProps {
  propStyle: CSSProperties
}

function CustomComponent({ propStyle }: customComponentProps) {
  return (
    <div {...prop(baseStyles, propStyle)}>
      some text
    </div>
  )
}

The result is that the CustomComponent can have certain styles added and overriden.

export function Page() {
  const style = {
    color: "green",
    fontWeight: "bold",
    "&:hover": {
      color: "blue"
    }
  }

  return (
    <CustomComponent propStyle={style} />
  )
}

Unfortunately, this does not translate to my POC. It's vastly more complicated.

---

An example of my poc.

I'm instantiating the components via the styled api:

badge.css.ts

import { styled } from "@pigment-css/react";
import { Box as RaikouBox } from "@raikou/core";

export const Box = styled(RaikouBox)((props) => ({
  background: "orange",
}));

export const Section = styled("span")((props) => ({
  color: "green",
}));

export const Label = styled("span")((props) => ({
  color: "black",
}));

Badge.tsx (as a package)t:

import { Box, Section, Label } from "./Badge.css";
...

export const Badge = polymorphicFactory<BadgeFactory>((_props, ref) => {
...

return (
    <Box
      variant={variant}
      mod={{ block: fullWidth }}
      ref={ref}
      {...others}
    >
      {leftSection && (
        <Section
          data-position="left"
          sx={{
            background: "red",
          }}
        >
          {leftSection}
        </Section>
      )}
      <Label>{children}</Label>
      {rightSection && (
        <Section data-position="right">
          {rightSection}
        </Section>
      )}
    </Box>
  );
});

The problem I have using the css function. I'm unable to pass it any props. So instead I'm using styled api. I should be able to overwrite the styles? But using SX prop here I'm unable to do so. Also I tried the runtime example above, again wasn't able to get it working.

Btw, this was a test to see what was possible. As I'm still new to the library.

My actual use case is something like:

classNames.section is an object of styles.

<Section data-position="left" sx={...classNames.section}>
   {leftSection}
</Section>

As the component would be used in this manner:

import { Badge } from "@raikou/server";

export default function Page() {
  return (
    <Badge
      classNames={{
        root: {
          color: "purple",
        },
        section: {
          background: "red"
        }
      }}
      leftSection="$$"
    >
      hello
    </Badge>
  );
}

Hopefully this makes more sense now?

Oh to clarify as well. All the values passed are static. None of them are dependent on props themselves. So this is all focused on buildtime.

[brijeshb42]

I'd say this is more suited when atomic css is involved, since here, you'd want to follow stylex's principle of last passed style always gets applied instead of last defined styles which would require deduping classnames of similar css properties. Current or near future implementation of Pigment CSS won't be solving for this particular use-case.

[paulm17]

@brijeshb42 Alright, good to know! Many thanks!

[oliviertassinari]

One of my aspirations for my own tech stack is at scale to not break the bank in production. So if I can reduce the css payload significantly. I'm all for it.

@paulm17 Pigment CSS relies on CSS Modules, CSS Modules can be code-split by the bundler based on what's visible on the screen. These CSS files can also be removed from the DOM when moving to a different page.

Atomic CSS shines when you have large CSS files and you don't code-split.
For example, we can compare facebook.com StyleX CSS file, they style the whole app with it:

with https://vercel.com homepage, it's written with CSS Modules:

The difference isn't that significant with Next.js. For example with https://vitejs.dev/guide/features.html#css-code-splitting it might work even better.

Now, we could consider an atomic CSS mode in the future, like even with CSS Modules code split, it could bring another level of performance in addition to code splitting.

[Axe1200]

Good question! From what I understand, atomic styles might be planned for a future release, but nothing official has been mentioned yet.

[LorenDorez]

I have a question about how to leverage Pigment-CSS with runtime theme support.

I see in the Pigment docs there ways to handle runtime based css for a component and separately about support things in the webpack/nextjs configs but I need a merge of the 2.

We have a SaaS based product that builds a custom theme at runtime based on the tenant's settings and then use the theme through the app. This is all don't in the app.jsx

Is there a way to do that with pigment as well are are we going yo start needing to used styled() everywhere now

[LorenDorez]

I dont think im explaining it very well.

So in our app.jsx we make a call like this, in which we create a theme object with various values from Runtime that are passed down to the app.jsx via props. Rough example below

const theme = createTheme({
  pallette: {
    primary: {
      main: props.dbValue,
    },
    secondary: {
      main: props.dbValue,
    }
  },
});

We then pass this runtime theme to the ThemeProvider with the following example:

<ThemeProvider theme={theme}>
  <MyCustomComponent />
</ThemeProvider>

Then when we use any MUI component it will naturally pull in the Runtime Primary/Secondary colors automatically. If we have some components that wrap MUI components or that use Styled() we again have access to this runtime variable.

1. How do we override the theme create in the config with runtime values and have that trickle down to all the nested MUI components? is there like an UpdateTheme() hook?
2. Can we use the same <ThemeProvider> and subsequent useTheme

[LorenDorez]

@brijeshb42 any update to my last comment?

[brijeshb42]

You can easily do so using a <style> tag in your document head. You can fetch your theme config from backend and override CSS variables either using inline style on a div or you can create a dynamic css and append it to the head tag at runtime like -

const css = `
  --palette-primary-main: ${backend.value.primary.main}
  /* similarly set other variable values */
`;

// on CSR apps
const style = document.createElement('style')
document.head.appendChild(style)

// on SSR apps
<style>{css}</style>

We'll also be providing an export from @pigment-css/react to help you do the same. But it's not there right now as we are still ideating it.

[LorenDorez]

Awesome that's for the info and examples. Also just a shout out to all the hard work you guys have done getting pigment off the ground. Can't wait to start using it more in our MUI based areas/apps

[Axe1200]

Totally agree! Huge kudos to the team for getting Pigment off the ground. Excited to see it in action in MUI apps!

[jeremytenjo]

Please don't forget about the css prop. It is extremely powerful and It provides the same appeal as Tailwind but it allows us to keep using more natural css.

[Axe1200]

Absolutely! The css prop is super powerful—it gives the utility of Tailwind while letting us write more natural CSS. Definitely don’t want it forgotten.

[kxseilerjo]

How does this affect/relate to Joy, especially regarding the efforts to rely on CSS-variables where possible?

[danilo-leal]

Heya @kxseilerjo. I'm not sure we can say the details yet, as we're primarily focused on converting Material UI components for now. Generally speaking, we'll return the focus to Joy UI together with the Material UI v7 cycle. We'll iron out the Material UI <> Joy UI and Joy UI <> Pigment CSS relationship then.

[Axe1200]

Great question! I’m also curious how this ties into Joy, especially with the push to rely on CSS variables. Will Pigment fully integrate with that approach or are there trade-offs?

[experimarketing]

I have an app that is built from dynamic settings. So the setttings are fetched and then merged into the build at run time.

So, I can inject any available sx properties this way.

It allows me to customize a version of the app per tenant.

Will I be able to do this with pigment?

[experimarketing]

I read that eventually you are moving completely to pigment, which I can understand why for apps that are completely built at run time.

So, does that mean that this use case will be completely unsupported by MUI in the future?

[aarjithn]

You could probably set the dynamic settings as css vars instead and have it set values in runtime - that should work

[experimarketing]

I am not sure I understand this 100%. From the examples I have seen, I would have to define all possible css vars to be able to use the same system as I am using now.

Because I don't know which css vars will be needed at build time for a Box component, for example. There could be none, 1, 2, etc. for each instance of the Box component. Meaning they could all be different.

Maybe I am misunderstanding how it would be implemented.

[experimarketing]

I just wanted to add the explanation for why I am doing things this way, in case it helps to understand it.

The main reason I am doing this is that it allows me to change a client's app without needing to do a redeployment of the code base, which might introduce bugs for other tenants.

And because no deployment is needed, I can make changes and iterate very quickly which gives a much better outcome for the client. It makes for very slightly slower app performance, but it is much faster in terms of making changes.

[aarjithn]

So for a box lets say you change padding, margin, boxShadow, borderRadius for eg. define all these with standard values at build time. and change it in runtime. It's a chore to define all possible properties for sure, but if you can limit it might be manageable.

[povilass]

As I can see PigmentCSS focused on MPA(multi-page app, NextJs, and so on). Does SPA (single-page app) with PigmentCSS still work similarly to Emotion? Will it include some sort of plugin for Webpack/Esbuild? Because there is nothing about this in the docs https://mui.com/material-ui/migration/migrating-to-pigment-css/

[GMchris]

I have a use case similar to @experimarketing . We have a base theme that's applied on page load, but immediately after a request is made which fetches a custom them our users can configure. It alters things like the primary.main color and the number in shape.radius.

Unlike experimarketing's example however, all of this happens by merging the base and user themes and feeding the result to the CssVarsProvider. What I would imagine this does is simply change the values for all the css variables which were generated by the theme, but I noticed in the migration guide you're supposed to pass your theme to a vite plugin at build time, so Im unsure.

[acomanescu]

@GMchris, @experimarketing Hi there! Depending on the adjustments you need to the base theme, I would override the styles using the CSS variables the theme exposes. By doing so, you can override the styles at any point. You can even unmount that customization and get back to standard (the built theme).

[experimarketing]

@acomanescu After doing some research on this and thinking more about it, I don't think that using CSS vars allows me to do what I need. There are hundreds of css variables per component. Generally, I will only use a few, but occasionally you need to really customize a component. And I need to be able to do that when needed. So, I don't think this works for my use case.

Does anyone know what the roadmap is for CSS for MUI?

[siriwatknp]

https://mui.com/blog/2026-and-beyond/#pigment-css
Sad to announce that we are not continuing the work on Pigment CSS.