Things to consider when migrating component's styles to emotion.
In v4 we were defining the styles like:
export const styles = (theme) => ({
/* Styles applied to the root element. */
root: {},
/* Styles applied to the root element if `container={true}`. */
container: {
boxSizing: 'border-box',
display: 'flex',
flexWrap: 'wrap',
width: '100%',
},
/* Styles applied to the root element if `item={true}`. */
item: {
boxSizing: 'border-box',
margin: 0, // For instance, it's useful when used with a `figure` element.
},
// ...
}In v5, we are using the styled() (named experimentalStyled() for now) utility for creating the components. This means, that we no longer have keys for specifying styles for specific props or slots, so we need to convert these keys to conditional spreading based on prop values, if they are based on a prop, or to completely different styled components, if they are slots. The previous example would look something like this:
const GridRoot = experimentalStyled(
'div',
{},
{
name: 'MuiGrid',
slot: 'Root',
overridesResolver, // we'll explain this part later
},
)(({ theme, styleProps}) => ({
...(stylesProps.container && { // apply these styles if container={true}
boxSizing: 'border-box',
display: 'flex',
flexWrap: 'wrap',
width: '100%',
}),
...(stylesProps.item && { // apply these styles if item={true}
boxSizing: 'border-box',
margin: 0, // For instance, it's useful when used with a `figure` element.
})
}));If there are some slots, it would look like this:
// Button styles
const styles = (theme) => ({
root: {
minWidth: 64,
padding: '6px 16px',
},
label: {
display: 'flex',
}
})const ButtonRoot = experimentalStyled(
'div',
{},
{
name: 'MuiButton',
slot: 'Root',
overridesResolver, // we'll explain this part later
},
)({
minWidth: 64,
padding: '6px 16px',
});
const ButtonLabel = experimentalStyled(
'div',
{},
{
name: 'MuiButton',
slot: 'Label',
},
)({
display: 'flex',
});Note that we are using the styleProps for accessing the props value. This is done for mainly two reasons:
- having one prop that is a collection of all related styling props, helps us in terms of perf to decide more easily which props should we spread on the HTML element and which should be ignored.
- having a separate prop for this, can help us easily extend it to contain state as well as some derivative props which are calculated based on other props.
- By defining the styles in one object, you are basically spreading all styles inside the style function result, which means that if you define the same key multiple times, it will override what you had defined before. This is usually what you want, but can be tricky when it comes to pseudo or class selector, breakpoints, etc. For example, spreading
':hover': {}somewhere along the object will replace all definition for the':hover'styles you had before. To avoid this issue, we recommend you either spread all styles for the specific selector in one place, by moving the condition inside that definition or use multiple callbacks when defining the styles. You can see an example of the first one on the Button component and for the second one on the Container component - If you found throughout the styles selectors like
$item, you will need to replace them with a class (usually some of the classes available on the componentClasses object we export - more on this later). For example:
-'& > $item': {
+[`& > .${gridClasses.item}`]: {
maxWidth: 'none',
},I've mentioned that we are using the experimentalStyled(), now we will see what params we need to provide for each component that we create.
The first parameter of the experimentalStyled() is the element or component that should serve as a base for the component. It can be a simple HTML element, like div, or a different component. For example, the ButtonRoot component is defined on top of the ButtonBase.
The second parameter are additional option props for the styled() utility that comes from the @material-ui/styled-engine (emotion or styled-components), like label, shouldForwardProp, target. These are set by default for you, but if you need to opt-out you can do it.
Finally, the third argument is the overrideResolver function, which based on the props and the style overrides coming from the theme, will create additional styles that will be applied on top of the default component styles. Here is one example of how the function can look like:
const overridesResolver = (props, styles) => {
const { styleProps } = props;
return deepmerge(styles.root || {}, {
...styles[styleProps.variant],
...styles[`${styleProps.variant}${capitalize(styleProps.color)}`],
...styles[`size${capitalize(styleProps.size)}`],
...styles[`${styleProps.variant}Size${capitalize(styleProps.size)}`],
...(styleProps.color === 'inherit' && styles.colorInherit),
...(styleProps.disableElevation && styles.disableElevation),
...(styleProps.fullWidth && styles.fullWidth),
[`& .${buttonClasses.label}`]: styles.label,
[`& .${buttonClasses.startIcon}`]: {
...styles.startIcon,
...styles[`iconSize${capitalize(styleProps.size)}`],
},
[`& .${buttonClasses.endIcon}`]: {
...styles.endIcon,
...styles[`iconSize${capitalize(styleProps.size)}`],
},
});
};You will see here that, based on the values inside the styleProps we decide which overrides we need to apply, for example, if the styleProps.disableElevation is true, we will apply the styles.disableElevation overrides (line 10 on the example above).
For the slots, we need to use the class selector for the appropriate slot when adding the overrides, we have in the example above overrides for the label, startIcon and endIcon slots accordingly.
We expect each component to export as part of its package object containing the default utility classes as well as a helper function for generating utility classes. For creating this you should use the generateUtilityClass and generateUtilityClasses helpers from @mateiral-ui/unstyled. Here is an example of this:
import { generateUtilityClass, generateUtilityClasses } from '@material-ui/unstyled';
export function getButtonUtilityClass(slot) {
return generateUtilityClass('MuiButton', slot);
}
const buttonClasses = generateUtilityClasses('MuiButton', [
'root',
'label',
'text',
'textInherit',
'textPrimary',
'textSecondary',
'outlined',
'outlinedInherit',
'outlinedPrimary',
'outlinedSecondary',
// ...
]);
export default buttonClasses;These utility classes are used later in the tests to ensure that the logic of the component is correct. Also, they are useful when defining the styles if any of the utility classes should be used as selectors.
In the component's logic, you need to actually add these classes to the rendered tree based on the styleProps. We do this by defining a new useUtilityClasses hook. Here is an example of it:
const useUtilityClasses = (styleProps) => {
const { color, disableElevation, fullWidth, size, variant, classes = {} } = styleProps;
// Define here key for each of the slots of the component
const slots = {
root: [
'root',
variant,
`${variant}${capitalize(color)}`,
`size${capitalize(size)}`,
`${variant}Size${capitalize(size)}`,
color === 'inherit' && 'colorInherit', // some classes may be added conditionally based on a prop
disableElevation && 'disableElevation',
fullWidth && 'fullWidth',
],
label: ['label'],
startIcon: ['startIcon', `iconSize${capitalize(size)}`],
endIcon: ['endIcon', `iconSize${capitalize(size)}`],
};
// always use this utility for generating the classes for the slots
// it will make sure that both the utility and props' classes will be applied
return composeClasses(slots, getButtonUtilityClass, classes);
};When you use this inside the component, make sure that you invoke it with the styleProps and make sure that those contain the props' classes, so that overrides will be applied.
You need to make sure you use the unstable_useThemeProps hook from @material-ui/core/styles, so that theme's default props will be merged with user-defined.
Usually each component's render method, will start with using this hook:
const Grid = React.forwardRef(function Grid(inProps, ref) {
const props = useThemeProps({ props: inProps, name: 'MuiGrid' });
// ...
} You need to make sure that you will use the correct name here, as it is used as a key in the theme's components definition.
In addition to the component's props, this hook returns also the isRtl and theme props, which can be accessed inside the rendered tree.
Each component that you create with the experimentalStyled() utility should be used somehow in your render tree. The ComponentRoot should be returned as the root of your rendered tree and it usually requires the as property set to the component prop if available in the core component. You need to make sure you also provide the stylesProps as well as the classes['slot'] which we generated with the useUtilityClasses hook.
All components that are created using experimentalStyled(), have the support for the sx prop. Hence, this prop needs to be added to the components' props.
For the test to work as expected, you need to first import the componentClasses and consider them as classes throughout all test suites, instead of generating them with getClasses().
In addition to this, you need to convert the describeConformance to describreConformanceV5. You will most likely need to add some additional options there. For this, I recommend following what is done in the Button.test.js.
There may be required some additional updates on the tests, based on how the generated styles are being tested, but this is a per-component basis.
After doing the changes, it's time to test that everything works fine. You should follow the following steps:
- All tests should be green, you can verify this both locally or on the PR's CI
- There should be no argos (screenshot) differences on the PR
- Run locally the docs and check out the component's docs page. It should run without any errors or visual issues
If yarn workspace framer build is failing, you will need to add the new sx prop in the ignoredProps for the compoennt you are migrating. For example:
diff --git a/framer/scripts/framerConfig.js b/framer/scripts/framerConfig.js
index fb02f439b6..526d4d294a 100644
--- a/framer/scripts/framerConfig.js
+++ b/framer/scripts/framerConfig.js
@@ -225,6 +225,7 @@ export const componentSettings = {
},
Paper: {
ignoredProps: [
+ 'sx',
// FIXME: `Union`
'variant',
],
Could you add to this was it how to test the components locally with npm?