[docs] Inconsistent documentation about importing "styled"

[Paki90]

Related page

https://v5.mui.com/material-ui/migration/v5-style-changes/#styled

Kind of issue

Unclear explanations

Issue description

Currently we are still using mui5 and planning to do migration to mui6. What I personally noticed that there is been inconsistency in the documentation about using styled in the documentation for migration from 4 to 5th version.
https://v5.mui.com/material-ui/migration/v5-style-changes/#styled
import { styled } from '@mui/styles';
here is suggested that styled should be imported from mui/styles

https://v5.mui.com/system/styles/basics/
here is clearly written that mui/styles are deprecated and it must be use mui/system instead

https://v5.mui.com/system/styled/
import { styled } from '@mui/system';
here is suggested that styled should be imported from mui/system

https://v5.mui.com/material-ui/migration/troubleshooting/#typeerror-cannot-read-properties-of-undefined-reading-pxtorem
https://v5.mui.com/material-ui/migration/migrating-from-jss/#1-use-styled-or-sx-api
import { styled } from '@mui/material/styles';
here are examples where is suggested that styled should be imported from mui/material/styles

In our solution: styled, theme, useTheme, SxProps are imported from mui/material/styles (if you think one of these should not be part of mui/material/styles, let me know) . Here are examples how it is used:

const AccordionSummary = styled((props: AccordionSummaryProps) => (
    <MuiAccordionSummary
        expandIcon={props.expandIcon}
        {...props}
    />
))(({ theme }) => ({
    backgroundColor: theme.palette.background.paper,
    minHeight: "32px",
    flexDirection: 'row-reverse',
    '& .MuiAccordionSummary-expandIconWrapper.Mui-expanded': {
        transform: 'rotate(90deg)',
    },
    '& .MuiAccordionSummary-content': {
        //margin: theme.spacing(1),
        margin: "0px 0px 0px 6px",
    }
}));

const Accordion = styled((props: AccordionProps) => (
    <MuiAccordion disableGutters elevation={0} square {...props} />
))(() => ({
    '&:not(:last-child)': {
        borderBottom: 0,
    },
    '&:before': {
        display: 'none',
    },
}));

We do not use any import from mui/system and default styling engine Emotion is not in use even it has dependencies and required to be installed.

Context

There are certain things to declare before we migrate to mui6:

1. What is correct import styled - from mui/material/styles or from mui/system?
2. Can we continue using styled in mui6 or is it mandatory to change into something different?
3. If styled is outdated/deprecated in future then we need to suggestion what is best and easiest transition from examples provided in "Issue description". The default styling engine of Material UI v6 is still Emotion but from given documentation for migration to mui6 there is claim that it is recommended that it needs to fully migrate to Pigment CSS

It can work alongside Emotion to ease the migration process, but it is recommended to fully migrate to Pigment CSS in the end.

Does it mean that we should go directly to Pigment CSS? What would be the best tool to have migration from styled to Pigment CSS? Appreciate for any help

Search keywords: styled, mui5, mui6, import styled

[mnajdova]

Hi, this migration guide is intended to be done step by step. The step: https://v5.mui.com/material-ui/migration/migrating-from-jss/ will finally guide you to using styled from '@mui/material/styles' as this is the Emotion implementation. To specifically answer your questions:

1. What is correct import styled - from @mui/material/styles or from @mui/system?

For using Emotion, you should use @mui/material/styles

2. Can we continue using styled in mui6 or is it mandatory to change into something different?

You can still use styled in v6, you can even still use Emotion (this is the production ready implementation

3. If styled is outdated/deprecated in future then we need to suggestion what is best and easiest transition from examples provided in "Issue description". The default styling engine of Material UI v6 is still Emotion but from given documentation for migration to mui6 there is claim that it is recommended that it needs to fully migrate to Pigment CSS

Piigment CSS is still not stable, it is intended for people who want to give it an early try and provide feedback, it is not production ready. This is why Emotion is still the default and recommended styling engine. We are not going to be moving away from the styled() API for now, my only recommendation would be to use the variants API instead of dynamic styles, check https://stackblitz.com/edit/react-vyn3bq?file=Demo.tsx for more details.

I hope this explanation helped, let me know if you have more questions.

[Paki90]

thank you for providing the information. Since styled from mui/material/styled will be not deprecated in the future then this conversation can be closed. Anyhow I understand migration guide is done step by step and documentation was gradually updated i still think that suggestion about importing styled imported from mui/styles (https://v5.mui.com/material-ui/migration/v5-style-changes/#styled ) should be corrected. If I remember, from begging of mui5 mui/styles was marked as deprecated so there is no need to be part of documentation.

[mnajdova]

I still think that suggestion about importing styled imported from mui/styles (https://v5.mui.com/material-ui/migration/v5-style-changes/#styled ) should be corrected. If I remember, from begging of mui5 mui/styles was marked as deprecated so there is no need to be part of documentation.

The idea was you can finish the migration to v5 and still use JSS for your custom style overrides. Then, if you decide to go completely to Emotion, you can follow the next guides :)

[mnajdova]

I will let @samuelsycamore to decide on the best course of action, I am fine with leaving it as is.

[samuelsycamore]

We've heard this feedback a few times now—it's understandably confusing if you're jumping around to find a solution and not necessarily reading the migration doc from start to finish. I think this is one of the main culprits that's contributing to the confusion:

The styled JSS utility is no longer exported from @mui/material/styles. You can use the one exported from @mui/styles instead.

I think this could be rephrased to explicitly state here that this is a temporary solution while you're in the process of migrating your app away from this deprecated package altogether. Something like this:

Since Material UI v5 doesn't use JSS, the JSS-based styled utility exported by @mui/material/styles has been replaced with an equivalent Emotion-based utility that's not backwards compatible. While migrating your app away from JSS, you can temporarily import the JSS-based utility from the deprecated @mui/styles package before refactoring your components further.

Is that more clear?

[github-actions]

This issue has been closed. If you have a similar problem but not exactly the same, please open a new issue.
Now, if you have additional information related to this issue or things that could help future readers, feel free to leave a comment.

Note

@Paki90 How did we do? Your experience with our support team matters to us. If you have a moment, please share your thoughts in this short Support Satisfaction survey.