Bringing consistency to Material UI customization APIs

The Material UI team is working on two initiatives to standardize the Material UI API: The first applies to overriding inner elements, and the second applies to component CSS classes. In both cases, the purpose is to provide a more consistent developer experience for the community.

Let's explore how these changes are taking shape:

Inner element overrides

Because Material UI components often contain multiple DOM nodes, it's common to need to modify the structure, behavior, and style of inner elements. For example, you might want to modify the Slider's thumb element to grow in size when dragged:

You can achieve this by providing custom components through the slots prop. The demo above provides a custom thumb component that uses the Slider's internal dragging and focusedThumbIndex states to change its appearance. Open the CodeSandbox to see the implementation.

The problem is that this slot pattern exposed through the slots prop is not consistent across the library. Some components implement the slots prop, but others have a components prop, which works the same as the slots prop. Other components have props named <SlotName>Component for more specific use cases—for example, the Accordion features a TransitionComponent prop for implementing custom transitions.

The same inconsistencies are found with the slotProps prop, which is used to provide custom props to inner elements. Some components have the slotsProps prop; others have a componentsProps prop; and still others have props named <SlotName>Props.

This lack of consistency leads to unnecessary complexity for both developers and maintainers. To resolve this, the slots and slotProps API will be standardized across all components, and the analogous APIs will be deprecated and eventually removed.

Component CSS classes

The most common way to customize a component's look and feel is to target its CSS classes. For example, you might want to customize a Chip's primary color and set it to a different color when it's clickable:

You can do this by targeting chipClasses.colorPrimary and chipClasses.clickable, respectively. The demo above targets .MuiChip-colorPrimary and .MuiChip-clickable.MuiChip-colorPrimary to achieve this result. Open the CodeSandbox to see the implementation.

The problem is that you could also use the chipClasses.clickableColorPrimary composed class, which composes the atomic clickable and color classes. These composed classes bloat the API without adding significant improvements: For example, this pattern adds 26 possible CSS classes to the Chip component.

The composed classes also reduce the predictability of the CSS classes API, as the compose order and which props get composed are arbitrary decisions. This adds unnecessary cognitive overhead for developers as well as significant complexity for maintainers. Because of these issues, composed CSS classes will be deprecated and eventually removed in favor of atomic class alternatives.

Standardization process

This initiative aims to improve the developer experience for the Material UI community. To provide the smoothest migration from the inconsistent APIs, they will be deprecated first and removed later, giving you plenty of time to adjust. With each deprecation, we'll update the migration guide and provide codemods to simplify the process.

As always, we'd love to hear what you think! Please open a GitHub issue if you encounter any unexpected behavior with the standardized APIs or if you have any other suggestions you'd like us to discuss.