How should we document the Overriding props across all MUI products?

[mapache-salvaje]

As I understand, historically, what I'll call the "Overriding props" (component, components, componentsProps, slots, slotProps) are a relatively new concept—hence why we don't really have a name for them as a group 😅—and they have not really been exposed until recently. As a result, they aren't documented very well across MUI's products where they are present.

Starting with the MUI Base docs (#32072), we began systematically documenting these props on each individual component page, assuming that devs interested in maximizing their customization options (i.e. ideal Base users) would want to know that these are available on every component. We also included details on the Base Usage page.

When I started auditing the Joy UI docs (#33998), we decided it would be best to only mention the relevant Overriding props on each component page—for example, don't mention componentsProps when the component only has a root slot (meaning this prop is unnecessary).

Following a discussion with the Core team about how to standardize our documentation of the Overriding props, we decided that:

• each product should probably handle the docs around these props slightly differently—you're more likely to use them in Base than in Material UI, for example
• we need a dedicated page in the docs for each product, possibly labelled as an "Advanced" topic, that explains the usage of these props in detail

After I tried revising a Material UI component page to add this info, it became apparent that it may not be necessary to mention at all here—and maybe not for Joy UI or MUI Base, either. (See: #34892 (comment).)

Given the anatomy of the Joy UI Alert component (a single <div>), it's not hard to imagine swapping out that element for some other HTML tag (like a span) that can wrap simple text content. But the only example I could think of for the Material UI Alert (which has a more complex structure) would be to replace the parent <div> with something equivalent but semantically unique like an <aside> or a <section>, which doesn't seem like a realistic use case. Otherwise you could insert a custom React component, but then why use the Alert component at all? And I couldn't think of any good reason to override the interior slots. So maybe nobody actually needs to use these props with this component, even though they are technically available??

In the comment linked above, @oliviertassinari says that this info may be unnecessary to include on the component pages for any of our products. Should we remove it from the MUI Base component pages, and/or not include it in future revisions of Material UI and Joy UI component pages? cc: @michaldudak @danilo-leal @siriwatknp

In any case, I am going to move forward creating a guide on the usage of the Overriding props that we will be able to use across all of the Core products. I also plan to revamp the equivalent page in the X docs. But we need to reach a decision about whether or not to document these props on individual component pages, and if so, how they fit into the flow/structure of the component documents. (Do they belong under ## Anatomy? ## Customization? ## Advanced?)

[siriwatknp]

Speaking of Joy and Material UI, I think it is great that we have the anatomy section for each component but it should be on the API page because it is like a reference of the component.

The component page should contain demos that developers want to see first. I guess no one cared that much at first about the HTML produced by the components.

However, some components like Button, Link, or Typography should mention the overriding slot in the customization section because they are pretty common use cases and we could add a link to explain the slots on a separate page.

---

To answer your question:

we need to reach a decision about whether or not to document these props on individual component pages

I'd say it makes sense for some components that are likely to be changed to a different element. Additionally, we do need to explain the slots on all component's API pages.

Do they belong under ## Anatomy? ## Customization? ## Advanced?

For some components, e.g. Button, I lean toward ## Customization on the demo page.

For the API page, I lean toward ## Anatomy.

[mapache-salvaje]

Speaking of Joy and Material UI, I think it is great that we have the anatomy section for each component but it should be on the API page because it is like a reference of the component.

That is interesting—I hadn't considered moving this content to the API page. Should we do this for MUI Base as well? Or does it make sense to keep that info on the Component pages?

[michaldudak]

IMO, ideally a component page would have a couple of tabs: Overview/demos, anatomy, API.
Similarly to https://m3.material.io/components/buttons/overview