[docs] Revise "Component theming" and "How to customize" guides #31997

danilo-leal · 2022-03-26T18:17:09Z

I have followed (at least) the PR section of the contributing guide.

Took the liberty to revise some of this content, which I think are some of the most important in the docs. There were some general reorganizing opportunities that I found and some content optimization (excluding something mentioned twice). All of it was inspired by this issue, given we weren't mentioned about sx prop higher than the theme's styles overrides specificity.

Initially, I was only going for the "How to customize" page but ended up thinking that the best place to tackle the issue above was in the "Component theming" page instead. So, since I was there already, took the opportunity to go through it as well.

Please revise the accuracy of the rewritten content!

Deploy previews:

mui-bot · 2022-03-26T18:19:57Z

No bundle size changes

Generated by 🚫 dangerJS against ef3c447

docs/data/material/customization/how-to-customize/how-to-customize.md

docs/data/material/customization/theme-components/theme-components.md

siriwatknp · 2022-03-28T10:16:08Z

docs/data/material/customization/theme-components/theme-components.md


-`sx` is also compatible with theme style overrides if you prefer the shorthand notation.
+Note that some components expose a `color` prop, which has a lower specificty than the theme's styles overrides. For example, say you have customized `Link`'s color.


@danilo-leal I was wrong. The Link is actually a bug. This should have the highest priority <Link color="highest-priority-color">...</Link>.

You can remove this part and I will create a fix in a separate PR.

Makes sense! I was just thinking it was weird for the component color prop to have lower specificity... I'll correct this sentence!

@siriwatknp are you going to bump the specificity for each prop combination? Should we create an RFC for this and make it work consistent with Material UI? In this case, when would you ever need the props callback?

@mnajdova I am not sure I follow you. From my understanding, this is a bug on the Link component.

I would say that the Typography (and Link) are basically the ones that work differently, in the other components that theme overrides take precedence, for example take a look at the button - https://codesandbox.io/s/shy-dust-sdylec?file=/src/App.tsx

Co-authored-by: Siriwat K <siriwatkunaporn@gmail.com>

samuelsycamore

Solid improvements! I've just gone through how-to-customize and will come back to theme-components in the morning!

docs/data/material/customization/how-to-customize/how-to-customize.md

samuelsycamore · 2022-03-29T03:12:26Z

docs/data/material/customization/how-to-customize/how-to-customize.md


-Using the `styled()` utility offers a simple way for adding dynamic styles based on props.
+> ⚠️ Note that if you are using TypeScript you will need to update the prop's types of the new component.


Suggested change

> ⚠️ Note that if you are using TypeScript you will need to update the prop's types of the new component.

> ⚠️ Note that if you are using TypeScript you will need to update the prop types of the new component.

I feel like we should move this back right before the demo showing how it should be altered in TypeScript.

Before or after? Haven't altered its position, its in the same spot as in the current version.

docs/data/material/customization/how-to-customize/how-to-customize.md

docs/data/material/customization/theme-components/theme-components.md

samuelsycamore · 2022-03-29T15:23:17Z

docs/data/material/customization/theme-components/theme-components.md

+
+If you are not familiar with the `sx` prop, make sure you first check out [the concept around it](/system/the-sx-prop/) and [the difference with the `styled` utility](/system/styled/#difference-with-the-sx-prop).
+
+To have a similar shorthand CSS notation to the `sx` prop but within the theme, you can use `sx` inside the `stylesOverrides`.


Rephrasing.

Suggested change

To have a similar shorthand CSS notation to the `sx` prop but within the theme, you can use `sx` inside the `stylesOverrides`.

You can use the `sx` prop inside the `styleOverrides` key to modify styles within the theme using shorthand CSS notation.

Can we elaborate on why a developer would want to do this? And this would also be a good place to explain why this is "experimental."

@mnajdova anything you'd like to share about that?

Can we elaborate on why a developer would want to do this?

Mainly for conistency. If a developer is already used to the sx syntax and it's shorthands, it's limiting that it can be used on only one place (the sx prop). More over, if they want to convert from sx prop to styled(), or move the styles to the theme overrides, they would have to manually change the styles to comply with the other regular syntax. This utility helps them by doing it automatically and providing a better DX along the way.

It's experimental as it was added after the v5 stable release, and we usually export API like this as an experimental first, to see if there will be some unforeseen bugs and stabilize them later.

Let me know what you think, tackled these aspects.

docs/data/material/customization/theme-components/theme-components.md

docs/data/material/customization/how-to-customize/how-to-customize.md

docs/data/material/customization/theme-components/theme-components.md

danilo-leal · 2022-04-05T23:07:33Z

@siriwatknp & @mnajdova little bump in your notifications to get this one out!

siriwatknp

👍 Thanks for improving these important pages!

oliviertassinari · 2022-04-07T10:43:39Z

docs/data/material/customization/how-to-customize/how-to-customize.md


-Let's go back to the above demo. How can you override the slider's thumb?
+<img src="/static/images/customization/dev-tools.png" alt="dev-tools" width="796" style="margin-bottom: 16px;" />


The change of docs/public/static/images/customization/dev-tools.png looks blurry on my screen. Am I the only one? I mean:

a. https://mui.com/customization/how-to-customize/#overriding-nested-component-styles
b. https://deploy-preview-31997--material-ui.netlify.app/customization/how-to-customize/#the-sx-prop

a. looks better on my end. I'm raising this because it's not the first time I see this problem. What do you think of limiting the resolution to x2, would it solve the problem? Otherwise, could we try a fixed integer increment? Currently, we are doing x3.28, maybe x3 or x4 would look crisp?

Huh... looks a bit blurry to me too, now that I'm looking at it again. But I did export at 2x (don't know where you got x3.28 from!). Though the blurriness could be because I increased the image size a bit. Let me see if I can tweak it properly.

docs/data/material/customization/how-to-customize/how-to-customize.md

oliviertassinari · 2022-04-07T10:55:32Z

docs/data/material/customization/how-to-customize/how-to-customize.md


-⚠️ These class names can't be used as CSS selectors because they are unstable,
-however, MUI applies global class names using a consistent convention: `Mui[Component name]-[name of the slot]`.
+First, use your browser's dev tools to identify the class for the component slot you want to override:


I think that it was clearer before. We were explaining how to "identify the class" in logical order. How will people know that MuiSlider-thumb is the right selector when all they see is?

We do no longer explain it in the flow, but at the bottom of the section. I think that it requires developers to do back and forth to understand the whole process, which is not ideal.

You're right. Revisited this one now, let me know your thoughts.

… feedback

docs/data/material/customization/theme-components/theme-components.md

…to-customize-revision

docs/data/material/customization/how-to-customize/how-to-customize.md

docs/data/material/customization/theme-components/theme-components.md

danilo-leal · 2022-04-12T00:41:35Z

Commenting to bump this one up in y'all notifications!

siriwatknp

I thought I had already approved it 😂.

This header was changed in #31997, but it doesn't seem to need to be a h3, h2 seems enough, and retain the anchor link Signed-off-by: Olivier Tassinari <olivier.tassinari@gmail.com>

danilo-leal and others added 4 commits March 22, 2022 10:33

initial commit

25b712c

iteration

100e7a3

general revision

974ea77

component theming revision

b5307a1

danilo-leal added the docs Improvements or additions to the documentation label Mar 26, 2022

danilo-leal requested review from mnajdova, siriwatknp and samuelsycamore March 26, 2022 18:17

siriwatknp reviewed Mar 28, 2022

View reviewed changes

docs/data/material/customization/how-to-customize/how-to-customize.md Outdated Show resolved Hide resolved

siriwatknp reviewed Mar 28, 2022

View reviewed changes

docs/data/material/customization/how-to-customize/how-to-customize.md Outdated Show resolved Hide resolved

siriwatknp reviewed Mar 28, 2022

View reviewed changes

docs/data/material/customization/theme-components/theme-components.md Outdated Show resolved Hide resolved

siriwatknp reviewed Mar 28, 2022

View reviewed changes

Jun's review

f29a278

Co-authored-by: Siriwat K <siriwatkunaporn@gmail.com>

samuelsycamore reviewed Mar 29, 2022

View reviewed changes

mnajdova reviewed Mar 29, 2022

View reviewed changes

docs/data/material/customization/theme-components/theme-components.md Outdated Show resolved Hide resolved

mnajdova reviewed Mar 29, 2022

View reviewed changes

docs/data/material/customization/theme-components/theme-components.md Outdated Show resolved Hide resolved

samuelsycamore reviewed Mar 29, 2022

View reviewed changes

danilo-leal added 5 commits March 29, 2022 22:58

Sam's first batch of reviews

5f2bb54

Jun's review

273cd2a

trimming inspiration

e3b4ce1

Sam's second batch of reviews

832c3ec

remove excerpt about Link's color prop

15e12f0

siriwatknp reviewed Mar 30, 2022

View reviewed changes

docs/data/material/customization/theme-components/theme-components.md Outdated Show resolved Hide resolved

Jun's review: update code snippet

24b4bb2

danilo-leal requested review from samuelsycamore and mnajdova and removed request for mnajdova March 31, 2022 16:51

samuelsycamore reviewed Mar 31, 2022

View reviewed changes

Sam's review

c72125e

siriwatknp approved these changes Apr 6, 2022

View reviewed changes

clarifying about specificity

260faa1

oliviertassinari reviewed Apr 7, 2022

View reviewed changes

danilo-leal added 6 commits April 7, 2022 11:32

Olivier's review on using CSS jargon

9fd751e

reordering content on "Overriding nested component styles", Olivier's…

6ffc1c3

… feedback

tackle dev tool blurriness

b44e391

expand on using the experimental sx prop

bda05ff

line break for better review

5c0bc5d

explain why sx prop alone is stable but inside the theme is experimental

08070da

danilo-leal commented Apr 7, 2022

View reviewed changes

docs/data/material/customization/theme-components/theme-components.md Outdated Show resolved Hide resolved

Sam's review

1429338

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Apr 8, 2022

Merge branch 'master' of https://github.com/mui/material-ui into how-…

9cf2a44

…to-customize-revision

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Apr 8, 2022

danilo-leal requested review from samuelsycamore, oliviertassinari and siriwatknp April 8, 2022 13:32

samuelsycamore reviewed Apr 8, 2022

View reviewed changes

Sam's review

af44cf2

siriwatknp approved these changes Apr 12, 2022

View reviewed changes

samuelsycamore approved these changes Apr 12, 2022

View reviewed changes

danilo-leal added 2 commits April 12, 2022 17:09

small final tweaks

36436d4

yarn docs:typescript:formatted

ef3c447

danilo-leal merged commit de11911 into mui:master Apr 12, 2022

danilo-leal deleted the how-to-customize-revision branch April 12, 2022 21:43

ZeeshanTamboli mentioned this pull request May 16, 2022

[docs] Fix wrong code snippet for overriding styles in theme with a callback value #32781

Merged

1 task

oliviertassinari mentioned this pull request Apr 24, 2023

[docs] Fix anchor link in customization #37004

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Revise "Component theming" and "How to customize" guides #31997

[docs] Revise "Component theming" and "How to customize" guides #31997

danilo-leal commented Mar 26, 2022 •

edited

mui-bot commented Mar 26, 2022 •

edited

siriwatknp Mar 28, 2022

siriwatknp Mar 28, 2022

danilo-leal Mar 28, 2022

mnajdova Mar 29, 2022

siriwatknp Mar 30, 2022

mnajdova Apr 7, 2022

samuelsycamore left a comment

samuelsycamore Mar 29, 2022

mnajdova Mar 29, 2022

danilo-leal Mar 30, 2022 •

edited

samuelsycamore Mar 29, 2022

samuelsycamore Mar 29, 2022

danilo-leal Mar 30, 2022

mnajdova Apr 7, 2022

danilo-leal Apr 7, 2022

danilo-leal commented Apr 5, 2022

siriwatknp left a comment •

edited

oliviertassinari Apr 7, 2022 •

edited

danilo-leal Apr 7, 2022

oliviertassinari Apr 7, 2022 •

edited

danilo-leal Apr 7, 2022

danilo-leal commented Apr 12, 2022

siriwatknp left a comment


		`sx` is also compatible with theme style overrides if you prefer the shorthand notation.
		Note that some components expose a `color` prop, which has a lower specificty than the theme's styles overrides. For example, say you have customized `Link`'s color.


		Using the `styled()` utility offers a simple way for adding dynamic styles based on props.
		> ⚠️ Note that if you are using TypeScript you will need to update the prop's types of the new component.


		If you are not familiar with the `sx` prop, make sure you first check out [the concept around it](/system/the-sx-prop/) and [the difference with the `styled` utility](/system/styled/#difference-with-the-sx-prop).

		To have a similar shorthand CSS notation to the `sx` prop but within the theme, you can use `sx` inside the `stylesOverrides`.

	To have a similar shorthand CSS notation to the `sx` prop but within the theme, you can use `sx` inside the `stylesOverrides`.
	You can use the `sx` prop inside the `styleOverrides` key to modify styles within the theme using shorthand CSS notation.


		Let's go back to the above demo. How can you override the slider's thumb?
		<img src="/static/images/customization/dev-tools.png" alt="dev-tools" width="796" style="margin-bottom: 16px;" />

[docs] Revise "Component theming" and "How to customize" guides #31997

[docs] Revise "Component theming" and "How to customize" guides #31997

Conversation

danilo-leal commented Mar 26, 2022 • edited

mui-bot commented Mar 26, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samuelsycamore left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danilo-leal Mar 30, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danilo-leal commented Apr 5, 2022

siriwatknp left a comment • edited

Choose a reason for hiding this comment

oliviertassinari Apr 7, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oliviertassinari Apr 7, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danilo-leal commented Apr 12, 2022

siriwatknp left a comment

Choose a reason for hiding this comment

danilo-leal commented Mar 26, 2022 •

edited

mui-bot commented Mar 26, 2022 •

edited

danilo-leal Mar 30, 2022 •

edited

siriwatknp left a comment •

edited

oliviertassinari Apr 7, 2022 •

edited

oliviertassinari Apr 7, 2022 •

edited