Skip to content

[docs] Polish migration guide #43021

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
oliviertassinari merged 1 commit into from
Aug 2, 2024
Merged

[docs] Polish migration guide #43021

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 47 additions & 47 deletions ...rial/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,6 @@ Bear in mind that the `.MuiAccordionSummary-gutters` class is applied to the com
```diff
-.MuiAccordionSummary-root .MuiAccordionSummary-contentGutters
+.MuiAccordionSummary-root.MuiAccordionSummary-gutters .MuiAccordionSummary-content
/>
```

```diff
Expand Down Expand Up @@ -221,7 +220,7 @@ The Autocomplete's `componentsProps` prop was deprecated in favor of `slotProps`
+ paper: { width: 12 },
+ popper: { width: 14 },
+ popupIndicator: { width: 16 },
}}
}}
/>
```

Expand All @@ -240,18 +239,18 @@ The AvatarGroup's `slotProps.additionalAvatar` was deprecated in favor of `slotP
```diff
<AvatarGroup
slotProps={{
- additionalAvatar: {color: "red"}
+ surplus: {color: "red"}
- additionalAvatar: { color: 'red' },
+ surplus: { color: 'red' },
}}
/>;
>
```

```diff
MuiAvatarGroup: {
defaultProps: {
slotProps: {
- additionalAvatar: {color: "red"}
+ surplus: {color: "red"}
- additionalAvatar: { color: 'red' },
+ surplus: { color: 'red' },
},
},
},
Expand All @@ -264,11 +263,11 @@ The AvatarGroup's `componentsProps` was deprecated in favor of `slotProps`:
```diff
<AvatarGroup
- componentsProps={{
- additionalAvatar: {color: "red"}
- additionalAvatar: { color: 'red' },
+ slotProps={{
+ surplus: {color: "red"}
+ surplus: { color: 'red' },
}}
/>;
>
```

```diff
Expand Down Expand Up @@ -329,7 +328,7 @@ The Badge's `components` prop was deprecated in favor of `slots`:
<Badge
- components={{ root: CustomRoot }}
+ slots={{ root: CustomRoot }}
/>
>
```

### componentsProps
Expand All @@ -340,7 +339,7 @@ The Badge's `componentsProps` prop was deprecated in favor of `slotProps`:
<Badge
- componentsProps={{ root: { testid: 'test-id' } }}
+ slotProps={{ root: { testid: 'test-id' } }}
/>
>
```

## Button
Expand Down Expand Up @@ -782,7 +781,7 @@ Here's how to migrate:

import { chipClasses } from '@mui/material/Chip';

MuiChip: {
MuiChip: {
styleOverrides: {
root: {
- [`&.${chipClasses.clickableColorPrimary}`]: {
Expand Down Expand Up @@ -888,11 +887,10 @@ Here's how to migrate:
- [`& .${chipClasses.deleteIconFilledColorSecondary}`]: {
+ [`&.${chipClasses.filled}.${chipClasses.colorSecondary} > .${chipClasses.deleteIcon}`]: {
color: 'red',
},
},
},
},
},

},
```

## CircularProgress
Expand All @@ -910,9 +908,9 @@ The CSS classes that composed the `circle` CSS class and `variant` prop values w
Here's how to migrate:

```diff
- .MuiCircularProgress-circleDeterminate
-.MuiCircularProgress-circleDeterminate
-.MuiCircularProgress-circleIndeterminate
+.MuiCircularProgress-determinate > .MuiCircularProgress-circle
- .MuiCircularProgress-circleIndeterminate
+.MuiCircularProgress-indeterminate > .MuiCircularProgress-circle
```

Expand All @@ -929,7 +927,7 @@ Here's how to migrate:
- [`& .${circularProgressClasses.circleIndeterminate}`]: {
+ [`&.${circularProgressClasses.indeterminate} > .${circularProgressClasses.circle}`]: {
color: 'red',
},
},
},
},
},
Expand Down Expand Up @@ -1141,7 +1139,7 @@ The Grid's `wrap` prop was deprecated in favor of `flexWrap` MUI System prop:
<Grid
- wrap="nowrap"
+ flexWrap="nowrap"
/>;
>
```

## ImageListItemBar
Expand All @@ -1163,13 +1161,13 @@ The CSS classes that composed the following props were deprecated:
Here's how to migrate:

```diff
- .MuiImageListItemBar-titleWrapBelow
-.MuiImageListItemBar-titleWrapBelow
+.MuiImageListItemBar-positionBelow > .MuiImageListItemBar-titleWrap
- .MuiImageListItemBar-titleWrapActionPosLeft
-.MuiImageListItemBar-titleWrapActionPosLeft
+.MuiImageListItemBar-actionPositionLeft > .MuiImageListItemBar-titleWrap
- .MuiImageListItemBar-titleWrapActionPosRight
-.MuiImageListItemBar-titleWrapActionPosRight
+.MuiImageListItemBar-actionPositionRight > .MuiImageListItemBar-titleWrap
- .MuiImageListItemBar-actionIconActionPosLeft
-.MuiImageListItemBar-actionIconActionPosLeft
+.MuiImageListItemBar-actionPositionLeft > .MuiImageListItemBar-actionIcon
```

Expand Down Expand Up @@ -1216,7 +1214,7 @@ The Modal's `components` prop was deprecated in favor of `slots`:
<Modal
- components={{ Root: CustomRoot, Backdrop: CustomBackdrop }}
+ slots={{ root: CustomRoot, backdrop: CustomBackdrop }}
/>
>
```

### componentsProps
Expand All @@ -1227,7 +1225,7 @@ The Modal's `componentsProps` prop was deprecated in favor of `slotProps`:
<Modal
- componentsProps={{ root: { testid: 'root-id' }, backdrop: { testid: 'backdrop-id' } }}
+ slotProps={{ root: { testid: 'root-id' }, backdrop: { testid: 'backdrop-id' } }}
/>
>
```

## OutlinedInput
Expand Down Expand Up @@ -1408,7 +1406,7 @@ Here's how to migrate:

import { toggleButtonGroupClasses } from '@mui/material/ToggleButtonGroup';

MuiButtonGroup: {
MuiButtonGroup: {
styleOverrides: {
root: {
- [`& .${toggleButtonGroupClasses.groupedHorizontal}`]: {
Expand All @@ -1418,9 +1416,10 @@ Here's how to migrate:
- [`& .${toggleButtonGroupClasses.groupedVertical}`]: {
+ [`&.${toggleButtonGroupClasses.vertical} > .${toggleButtonGroupClasses.grouped}`]: {
color: 'red',
},
},
},
},
},
},
```

## Tab
Expand Down Expand Up @@ -1451,7 +1450,8 @@ Here's how to migrate:
- [`& .${tabClasses.iconWrapper}`]: {
+ [`& .${tabClasses.icon}`]: {
color: 'red',
},
},
},
},
},
```
Expand All @@ -1471,9 +1471,9 @@ The CSS classes that composed the `direction` prop and `icon` prop were removed.
Here's how to migrate:

```diff
- .MuiTableSortLabel-iconDirectionDesc
-.MuiTableSortLabel-iconDirectionDesc
+.MuiTableSortLabel-directionDesc > .MuiTableSortLabel-icon
- .MuiTableSortLabel-iconDirectionAsc
-.MuiTableSortLabel-iconDirectionAsc
+.MuiTableSortLabel-directionAsc > .MuiTableSortLabel-icon
```

Expand All @@ -1490,7 +1490,7 @@ Here's how to migrate:
- [`& .${tableSortLabelClasses.iconDirectionAsc}`]: {
+ [`&.${tableSortLabelClasses.directionAsc} > .${tableSortLabelClasses.icon}`]: {
color: 'red',
},
},
},
},
},
Expand All @@ -1510,18 +1510,18 @@ All of the TextField's slot props (`*Props`) props were deprecated in favor of e

```diff
<TextField
- InputProps={CustomInputProps}
- inputProps={CustomHtmlInputProps}
- SelectProps={CustomSelectProps}
- InputLabelProps={CustomInputLabelProps}
- FormHelperTextProps={CustomFormHelperProps}
+ slotProps={{
+ input: CustomInputProps
+ htmlInput: CustomHtmlInputProps
+ select: CustomSelectProps
+ inputLabel: CustomInputLabelProps
+ formHelper: CustomFormHelperProps
+ }}
- InputProps={CustomInputProps}
- inputProps={CustomHtmlInputProps}
- SelectProps={CustomSelectProps}
- InputLabelProps={CustomInputLabelProps}
- FormHelperTextProps={CustomFormHelperProps}
+ slotProps={{
+ input: CustomInputProps
+ htmlInput: CustomHtmlInputProps
+ select: CustomSelectProps
+ inputLabel: CustomInputLabelProps
+ formHelper: CustomFormHelperProps
+ }}
/>
```

Expand Down Expand Up @@ -1615,9 +1615,9 @@ The CSS classes that composed the `line` CSS class and `orientation` prop values
Here's how to migrate:

```diff
- .MuiStepConnector-lineHorizontal
-.MuiStepConnector-lineHorizontal
+.MuiStepConnector-horizontal > .MuiStepConnector-line
- .MuiStepConnector-lineVertical
-.MuiStepConnector-lineVertical
+.MuiStepConnector-vertical > .MuiStepConnector-line
```

Expand Down
51 changes: 27 additions & 24 deletions docs/data/material/migration/migrating-to-v6/migrating-to-pigment-css.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ Before going through this guide, make sure you have [migrated to Material UI v6

## Introduction

The default styling engine of Material UI v6 is [Emotion](https://emotion.sh/docs/introduction). It lets you write styles in a CSS-in-JS fashion, which is great for dynamic styles that depend on states and props. However, it has some performance drawbacks when it comes to frequent re-renders because the style recalculation happens on the client-side. It also does not fully support [React Server Components](https://react.dev/reference/rsc/server-components), a new rendering paradigm that renders components ahead of time on the server.
The default styling engine of Material UI v6 is [Emotion](https://emotion.sh/docs/introduction).
It lets you write styles in a CSS-in-JS fashion, which is great for dynamic styles that depend on states and props. However, it has some performance drawbacks when it comes to frequent re-renders because the style recalculation happens on the client-side.
It also does not fully support [React Server Components](https://react.dev/reference/rsc/server-components), a new rendering paradigm that renders components ahead of time on the server.

Pigment CSS aims to solve these problems while keeping the same developer experience of writing styles in a CSS-in-JS fashion.
It can work alongside Emotion to ease the migration process, but it is recommended to fully migrate to Pigment CSS in the end.
Expand All @@ -15,7 +17,7 @@ It can work alongside Emotion to ease the migration process, but it is recommend

Pigment CSS can be used with one of the following frameworks:

- [Next.js App Router](https://nextjs.org/docs/app) with Webpack 5 (Turbo is not supported yet)
- [Next.js App Router](https://nextjs.org/docs/app) with Webpack v5 (Turbopack is not supported yet)
- [Vite](https://vitejs.dev/)

## Installation
Expand Down Expand Up @@ -102,7 +104,7 @@ Finally, import the stylesheet at the top of the layout file.
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';

+ import '@mui/material-pigment-css/styles.css';
+import '@mui/material-pigment-css/styles.css';

export default function RootLayout(props) {
return (
Expand Down Expand Up @@ -155,7 +157,7 @@ Finally, add the Pigment CSS stylesheet to the top of the main file.

```diff title="src/main.(js|tsx)"
import * as React from 'react';
+ import '@mui/material-pigment-css/styles.css';
+import '@mui/material-pigment-css/styles.css';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')).render(
Expand All @@ -171,11 +173,11 @@ Integrating Pigment CSS with Material UI requires you to configure the theme t
Add the following code to your [Next.js](#nextjs) or [Vite](#vite) config file:

```diff
+ import { extendTheme } from '@mui/material';
+import { extendTheme } from '@mui/material';

+ const pigmentConfig = {
+ theme: extendTheme(),
+ };
+const pigmentConfig = {
+ theme: extendTheme(),
+};
```

If you don't have a custom theme, you are ready to go. Start a development server by running:
Expand Down Expand Up @@ -211,6 +213,7 @@ import Card from '@mui/material/Card';

function App() {
const [color, setColor] = useState('#000000');

return (
<Card
sx={{
Expand Down Expand Up @@ -434,8 +437,8 @@ With Pigment CSS, any JSX element can accept the `sx` prop so it is **no** long
If you have custom components that are using `styled` from `@mui/material/styles`, change the import source to `@mui/material-pigment-css`:

```diff
- import { styled } from '@mui/material/styles';
+ import { styled } from '@mui/material-pigment-css';
-import { styled } from '@mui/material/styles';
+import { styled } from '@mui/material-pigment-css';
```
Comment on lines 439 to 442
Copy link
Member Author

@oliviertassinari oliviertassinari Jul 22, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm confused about this new package, I don't understand the direction. I think we need to move to a place where @mui/material is only exporting one thing: CSS, and developers can opt-in to copy the source if they want. We won't be able to get this by having material-ui specific packages. If we really need a separate package (I don't understand the breaking change argument because Pigment CSS is unstable, an intermediary package around it won't change it), I think we should use MUI System for it.

So can we not do this but move towards?

-import { styled } from '@mui/material/styles';
+import { styled } from '@pigment-css/react';

same for the other modules

-import { useTheme } from '@mui/material/styles';
+import { useTheme } from '@pigment-css/react';


Then, run the following codemod:
Expand Down Expand Up @@ -506,17 +509,17 @@ export default FlashCode;
To use layout components that are compatible with Pigment CSS, replace the following components with those from the adapter package:

```diff
- import Container from '@mui/material/Container';
+ import Container from '@mui/material-pigment-css/Container';
-import Container from '@mui/material/Container';
+import Container from '@mui/material-pigment-css/Container';

- import Grid from '@mui/material/Grid';
+ import Grid from '@mui/material-pigment-css/Grid';
-import Grid from '@mui/material/Grid';
+import Grid from '@mui/material-pigment-css/Grid';

- import Stack from '@mui/material/Stack';
+ import Stack from '@mui/material-pigment-css/Stack';
-import Stack from '@mui/material/Stack';
+import Stack from '@mui/material-pigment-css/Stack';

- import Hidden from '@mui/material/Hidden';
+ import Hidden from '@mui/material-pigment-css/Hidden';
-import Hidden from '@mui/material/Hidden';
+import Hidden from '@mui/material-pigment-css/Hidden';
```

:::info
Expand All @@ -533,16 +536,16 @@ Choose one of the following approaches:
Replace the `Box` component with the one from the adapter package:

```diff
- import Box from '@mui/material/Box';
+ import Box from '@mui/material-pigment-css/Box';
-import Box from '@mui/material/Box';
+import Box from '@mui/material-pigment-css/Box';
```

### Use HTML element

Pigment CSS can extract the `sx` prop from any JSX element, so there is no need to use the Box component.

```diff
- import Box from '@mui/material/Box';
-import Box from '@mui/material/Box';

function CustomCard() {
return (
Expand All @@ -554,7 +557,7 @@ Pigment CSS can extract the `sx` prop from any JSX element, so there is no need
+ <img src="..." sx={{ width: 24, height: 24 }}>
+ ...
+ </div>
)
);
}
```

Expand All @@ -577,8 +580,8 @@ declare global {
If you are using the `useTheme` hook, replace the import source:

```diff
- import { useTheme } from '@mui/material/styles';
+ import { useTheme } from '@mui/material-pigment-css';
-import { useTheme } from '@mui/material/styles';
+import { useTheme } from '@mui/material-pigment-css';
```

:::info
Expand Down
Loading