[docs] Add sx prop to readme (part 1)
#57
Conversation
There was a problem hiding this comment.
The shorthand properties (currently, the shorthand works but it's tied to MUI System styleFunctionSx). There is a plan to move to theme.unstable_sx so that developer can configure their own which will be a different PR.
This is very important, I would even wait with adding documentation until we have this. The sx prop currently is tight to a theme structure, that people may not be aware of. If we don't have a documentation about this, it looks like magic.
|
|
||
| The value provided to `sx` prop can be one of the following: | ||
|
|
||
| - a plain style object (recommended) |
| - a callback function that receives the [theme object](#theming) then return a plain style object: | ||
|
|
||
| ```js | ||
| <div sx={(theme) => ({ color: theme.colors.primary })} /> |
There was a problem hiding this comment.
Maybe we can add example that is not possible with an object, so that people are aware of what's the different use-case.
| - an array of plain style objects or callback functions. This is useful for applying conditional styles based on other variables: | ||
|
|
||
| ```js | ||
| <div |
|
|
||
| The value provided to `sx` prop can be one of the following: | ||
|
|
||
| - a plain style object (recommended) |
There was a problem hiding this comment.
I'd also mention static values.
| <div sx={{ display: 'flex', flexDirection: 'column' }}> | ||
| ``` | ||
|
|
||
| For a React component, it must spread the `className` and `style` to the underlying DOM element, otherwise the styles won't be applied. |
There was a problem hiding this comment.
nit: "spread" is just a way of passing several props at once. I think "pass" (or another word?) would work best here since some devs might think they're forced to spread props.
| For a React component, it must spread the `className` and `style` to the underlying DOM element, otherwise the styles won't be applied. | |
| For a React component, it must pass the `className` and `style` props to the underlying DOM element, otherwise the styles won't be applied. |
|
|
||
| ### Shorthand properties | ||
|
|
||
| > ⏳ **Coming soon**: We are working on the shorthand properties for `sx` prop. |
There was a problem hiding this comment.
This part seems to take for granted that users know about what shorthand properties are. Maybe a longer explanation, an example, or a link to an existing resource of why shorthand properties are useful is helpful.
There was a problem hiding this comment.
We can link to docs on mui.com
| <div sx={{ display: 'flex', flexDirection: 'column' }}> | ||
| ``` | ||
|
|
||
| For a React component, it must spread the `className` and `style` to the underlying DOM element, otherwise the styles won't be applied. |
There was a problem hiding this comment.
This line doesn't seem applicable. We can do without it because users don't have to care about the spread. Also, if they have their own className being passed to the element/component, we are the ones transforming that to take care of passing both the existing class and the generated class.
Also, we are typechecking it (when using typescript). So sx prop willl only be passed on components that actually accept it. This means, that component is aware of what to do with it.
| <AnyComponent sx={{ fontSize: 12, color: 'red' }} />; | ||
| ``` | ||
|
|
||
| > 💡 **Gotcha**: You don't need to pass `sx` prop to underlying component or DOM because it will be replaced with `className` and `style` props. |
NOT included in this PR: For part 2
styleFunctionSx). There is a plan to move totheme.unstable_sxso that developer can configure their own which will be a different PR.SxPropstypes for augmenting TypeScript HTMLAttribute interface to be able to usesxprop on an HTML element. I think this can be a separate PR. For now, we document the value asany.