[RFC] Rename of the `components` prop to `slots`

[michaldudak]

Problem

This is a continuation of #21453. With some hindsight, we have surfaced possible limitations:

1. In the documentation and comments we generally refer to sub-components of a component as "slots". However, the props to control these slots are called components and componentsProps (as per [RFC] What's the best API to override deep/nested elements? #21453). We have used "components" so far with the objective to be as close as possible to the React implementation. But is it intuitive?
2. There is an inconsistency in the casing (members of components are Pascal-cased, while members of componentsProps are camel-cased) when comparing the props side-by-side.

<Slider components={{ Root }} componentsProps={{ root: {} }} />

The current casing aims to be consistent with the React conventions. In React components are Pascal-cased while elements props are camel-cased. But is it intuitive?

Solution

Therefore, I propose the following:

1. Rename the components prop to slots.
2. Rename the componentsProps prop to slotProps.
3. Rename the members of slots to use camel-case (e.g. root instead of Root).

Execution

This obviously would be a breaking change. For stable packages, we should introduce a transition period where both sets of props would be available. We will then deprecate the old ones, and finally, remove them in a future major version. We could provide a codemod to aid in the transition.

As MUI Base is not stable yet, we may introduce this change sooner, without a transition period. The library hasn't been publicly announced yet, so there is an opportunity to introduce this change without impacting many developers.

Advantages

Rename of components and componentsProps

• Better alignment with the terms used throughout the documentation.
• Use of a less ambiguous and generic term ("component" has a much broader meaning than "slot").
• Shorter words require less typing and take less horizontal space in components' markup.

Camel-cased slots members

• It'll be consistent with componentsProps.* . I often cringe when writing a component and having to override componentsProps.root and components.Root
• Pascal-cased props/fields look weird and are not common in JS/TS
• It would match the capitalization we use in for the theme component overrides https://mui.com/material-ui/customization/theme-components/#global-style-overrides.
• I understand the reasoning behind introducing Pascal-cased identifiers (components are written this way by convention). However, what goes into a components.* doesn't have to be a React component (could be a div, for example). Besides, we don't actually pass components.* to JSX directly, so we don't have to rely on it being written in Pascal-case (we usually write const Root = components.Root ?? component ?? 'div')
• We've got the component prop, not Component
• It's easier to type - developers won't have to press Shift 🙂

Disadvantages

• Developers accustomed to the existing patterns will have to relearn them.
• Introducing breaking changes will require changes to downstream codebases.
• Some could argue that "components" is describing what the prop is doing more precisely. You might have to think twice about what's the returned type of the "slot" prop, while it could be more intuitive when seeing "components".

Benchmark

• https://github.com/straw-hat-team/adr/blob/master/adrs/1358452048/README.md

[oliviertassinari]

I have updated a bit the description to bring some of the initial rationales on why the previous terminology/API. I have raised how:

• in problem 1. using "slot" moves us a bit further away from the React terminology, meaning, we would decide to optimize for describing the concept over describing the expected type of the prop & how this is implemented. It feels like a tradeoff. It could make sense for the docs to focus on the concept, hence use "slots", and the API to focus on the implementation, hence use "components".
• in problem 2. using the same capitalization would move us a bit further away from the React consistency conventions, where the upper case if for React components types and the lower case is for the types of objects. It feels like a tradeoff.

Overall, no objections, it sounds like a step forward (more pros than cons).

I think that the question is about, how to actually make the change. I would be more in favor of moving slowly: keep all our products' API consistent, support both APIs, and have a migration period in the order of 24 months (one or two majors). We have done massive changes in v5, it didn't fly well, we likely have to rebuild trust with our audience now when it comes to BCs.

[michaldudak]

I propose the following approach to proceed with this further:

1. Add the slots and slotProps props to Material UI components that already support components/componentsProps. References to componentsProps exist in 17 components within @mui/material as of today.
2. In Material UI, add the deprecation notice to the components and componentsProps props in favor of the newly added ones.
3. Rename the components/componentsProps props in MUI Base and Joy UI. I don't see much value in keeping both components and slots in the transition period. Let's teach developers how to use the props we intend to keep. What's more, introducing a new library with already deprecated props wouldn't look well.

We can decide at a later stage when to remove the components/componentsProps from Material UI.

This will:

• keep our non-deprecated API consistent across packages: you'll be able to use slots across the board,
• teach developers the patterns we'd like to keep,
• not break anyone using the stable packages.

[oliviertassinari]

@michaldudak For the angle of how to implement the changes, I think that it could work, I would only add two things:

For 1. I think that we should also include all the demos in the docs.
For 2. I think that we should at least wait enough time to see how the community reacts to 1. The deprecations could happen as late as once we start to work on v6.

For the angle of either we should move forward. I think that ideally, we would want to get some feedback from the community, we are ultimately doing it for them. I'm not sure how. https://twitter.com/tannerlinsley/status/1531641545568333824 could be one way.
I think that feedback from MUI X would also be great. They are as much impacted by these changes, e.g. #33183 with @alexfauquette.

[michaldudak]

Agreed, both make perfect sense.

As for MUI X, @flaviendelangle also mentioned they'll be affected by these changes. I'm eager to know if you guys consider these changes worth pursuing.

[mapache-salvaje]

Just chiming in to say +1 to move forward with this! I think this concept and its implementation will be much easier for new users to grasp when the terminology is aligned here.

[michaldudak]

I've just created a poll to make a decision: #34080

[alexfauquette]

Maybe a dumb proposal, but could we use "component slot" instead of "slot" in the doc and keep the prop naming as it is?