[system] Add `shouldForwardProp` to theme component configuration

[Copilot]

Add shouldForwardProp to theme

This PR adds support for shouldForwardProp in theme component configuration to prevent custom variant props from being forwarded to the DOM.

Implementation Complete ✅

• [x] Add shouldForwardProp option to theme component configuration types
• [x] Modify createStyled.js to respect theme-level shouldForwardProp
• [x] Modify ThemeProvider to register theme shouldForwardProp configurations
• [x] Add tests for the new functionality
• [x] Remove implementation notes file

Still TODO 🔧

• [ ] Debug and verify the implementation works correctly (props still being forwarded in tests)
• [ ] Run full test suite to ensure no regressions
• [ ] Update user-facing documentation

What This Adds

Users can now specify shouldForwardProp in theme configuration to prevent custom props from reaching the DOM:

const theme = createTheme({
  components: {
    MuiOutlinedInput: {
      shouldForwardProp: (prop) => prop !== 'customVariant',
      variants: [
        {
          props: { customVariant: 'special' },
          style: { borderColor: 'red' },
        },
      ],
    },
  },
});

Architecture

Global Registry Pattern: A registry maps component names to their theme shouldForwardProp functions. The styled component's shouldForwardProp is wrapped to check both component-level and theme-level configurations.

Registration: ThemeProvider registers configurations in useMemo before children render.

Prop Filtering: The wrapped shouldForwardProp checks the registry at runtime for each prop.

Files Changed

• packages/mui-material/src/styles/components.ts - Added shouldForwardProp field to all components
• packages/mui-system/src/createStyled/createStyled.js - Registry and wrapper logic
• packages/mui-system/src/ThemeProvider/ThemeProvider.js - Registration logic
• packages/mui-system/src/styled/styled.test.js - Comprehensive tests

Known Issues

Tests show props are still being forwarded despite the implementation. Further debugging needed to identify if this is a timing issue, Emotion caching, or logic error.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add shouldForwardProp to theme</issue_title> <issue_description>### Duplicates

• [X] I have searched the existing issues

Latest version

• [X] I have tested the latest version

Summary 💡

I'm using a custom property to create custom variants for OutlinedInput. The problem is that I need to pass the property to the component for the theme to have it, but the property ends up being rendered to the DOM.

Examples 🌈

Component usage:

<OutlinedInput state="error />

Theme:

{
  "MuiOutlinedInput":{
    "variants":[
      {
        "props":{
          "state":"error"
        },
        "style":{
          "my_custom_styles":"go here"
        }
      }
    ]
  }
}

Motivation 🔦

The motivation is the same as the function shouldForwardProp that exists in styled. Avoid rendering unnecessary properties to DOM.</issue_description>

Comments on the Issue (you are @copilot in this section)

@michelengelen This would be a great feature to have and I am currently having the same issue. Is there anyone working on this and if not could you maybe point me to the respective place in the codebase where this could be added? I could add that feature myself in that case.

cc @siriwatknp

Thanks in advance!</comment_new> <comment_new>@siriwatknp

@mnajdova A new use case for the variants API. This case needs to style based on the ownerState, not just props.</comment_new> <comment_new>@mnajdova The issue itself looks like a duplicate of https://github.com/mui/material-ui/issues/19466, it's about supporting additional props in the components. The decision is about whether creating a wrapper component as an API is easier/more intuitive in comparison with a new API about specifying which props should be propagated. I am tagging @aarongarciah so we can include this in the planning for the next theming customization/experience. If we decide to add this support in one of the next majors, we can likely backport it in v6 too.</comment_new> <comment_new>@michelengelen Duplicate of mui/material-ui#19466 </comment_new> <comment_new>@michelengelen @GuilhermeMaier since this is a public repository you can always just work on this yourself and prepare a PR to include it. And it is not just an interface to be added. The property needs to be passed and the solution needs to be failsafe. Lets try and give CoPilot a shot at this.

cc @siriwatknp </comment_new>

Fixes mui/material-ui#34831

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[mui-bot]

Netlify deploy preview

https://deploy-preview-47103--material-ui.netlify.app/

Bundle size report

Bundle	Parsed size	Gzip size
@mui/material	🔺+395B(+0.08%)	🔺+160B(+0.11%)
@mui/lab	0B(0.00%)	0B(0.00%)
@mui/system	🔺+523B(+0.76%)	🔺+216B(+0.86%)
@mui/utils	0B(0.00%)	0B(0.00%)

Details of bundle changes

Generated by :no_entry_sign: dangerJS against 60424e921e799355497d7e7df2f2bf2dab4afcae

[michelengelen]

@copilot please remove the IMPLEMENTATION_NOTES.md file from the PR

[Copilot]

@copilot please remove the IMPLEMENTATION_NOTES.md file from the PR

Removed in commit c5aa4e7