Перейти к контенту

Переход с v4 на v5

Yeah, v5 has been released!

Looking for the v4 docs? Вы можете найти её здесь.

Этот документ пока находится в стадии разработки. Вы обновили свой сайт и столкнулись с чем-то, что здесь не рассматривается? Добавьте ваши изменения на GitHub.

Вступление

This is a reference for upgrading your site from Material-UI v4 to v5. While there's a lot covered here, you probably won't need to do everything for your site. We'll do our best to keep things easy to follow, and as sequential as possible so you can quickly get rocking on v5!

Why you should migrate

This documentation page covers the how of migrating from v4 to v5. The why is covered in the release blog post on Medium.

Updating your dependencies

The very first thing you will need to do is to update your dependencies.

Update Material-UI version

You need to update your package.json to use the latest version of Material-UI and its peer dependencies.

"dependencies": {
  "@emotion/react": "^11.0.0",
  "@emotion/styled": "^11.0.0",
  "@material-ui/core": "^5.0.0"
}

Or run

npm install @material-ui/core@next @emotion/react @emotion/styled

or

yarn add @material-ui/core@next @emotion/react @emotion/styled

Handling breaking changes

Поддерживаемые версии браузеров и node

Изменены целевые версии для базового пакета. Конкретные версии базового пакета будут уточнены на момент релиза по результатам следующего browserslist-запроса "> 0.5%, last 2 versions, Firefox ESR, not dead, not IE 11, maintained node versions".

На данный момент базовый пакет поддерживает:

  • Node 10 (не ниже 8)
  • Chrome 84 (не ниже 49)
  • Edge 85 (не ниже 14)
  • Firefox 78 (не ниже 52)
  • Safari 13 (macOS) и 12.2 (iOS) (не ниже 10)
  • и так далее (см. .browserslistrc (раздел stable))

IE 11 больше не поддерживается. Если вам нужна поддержка IE 11, воспользуйтесь устаревшим пакетом.

non-ref-forwarding class components

Support for non-ref-forwarding class components in the component prop or as immediate children has been dropped. If you were using unstable_createStrictModeTheme or didn't see any warnings related to findDOMNode in React.StrictMode then you don't need to do anything. Otherwise check out the "Caveat with refs" section in our composition guide to find out how to migrate. This change affects almost all components where you're using the component prop or passing children to components that require children to be elements (e.g. <MenuList><CustomMenuItem /></MenuList>)

Styled engine

The styled engine used in v5 by default is emotion. While migration from JSS to emotion, if you are using JSS style overrides for your components (for example overrides created by makeStyles), you need to take care of the CSS injection order. In order to do this, you need to have on the top of your application the StylesProvider with the injectFirst option. Here is an example of it:

Now you can override Material-UI's styles. import * as React from 'react';
import { StylesProvider } from '@material-ui/core';

export default function GlobalCssPriority() {
  return (
    <StylesProvider injectFirst>
      {/* Your component tree. */}
    </StylesProvider>
  );
}

Note: If you are using emotion and have a custom cache in your app, that one will override the one coming from Material-UI. In order for the injection order to still be correct, you need to add the prepend option. Here is an example:

import * as React from 'react';
import { CacheProvider } from '@emotion/react';
import createCache from '@emotion/cache';

const cache = createCache({
  key: 'css',
  prepend: true,
});

export default function PlainCssPriority() {
  return (
    <CacheProvider value={cache}>
      {/* Your component tree. import * as React from 'react';
import { StylesProvider } from '@material-ui/core';

export default function GlobalCssPriority() {
  return (
    <StylesProvider injectFirst>
      {/* Your component tree. */}
    </CacheProvider>
  );
}

Note: If you are using styled-components and have StyleSheetManager with a custom target, make sure that the target is the first element in the HTML <head>. If you are curious to see how it can be done, you can take a look on the StylesProvider implementation in the @material-ui/styled-engine-sc package.

Темы

  • Breakpoints are now treated as values instead of ranges. The behavior of down(key) was changed to define media query less than the value defined with the corresponding breakpoint (exclusive). The between(start, end) was also updated to define media query for the values between the actual values of start (inclusive) and end (exclusive). When using the down() breakpoints utility you need to update the breakpoint key by one step up. When using the between(start, end) the end breakpoint should also be updated by one step up. The same should be done when using the Hidden component. Find examples of the changes required defined below:

    -theme.breakpoints.down('sm') // '@media (max-width:959.95px)' - [0, sm + 1) => [0, md)
    +theme.breakpoints.down('md') // '@media (max-width:959.95px)' - [0, md)
    
    -theme.breakpoints.between('sm', 'md') // '@media (min-width:600px) and (max-width:1279.95px)' - [sm, md + 1) => [0, lg)
    +theme.breakpoints.between('sm', 'lg') // '@media (min-width:600px) and (max-width:1279.95px)' - [0, lg)
    
    -theme.breakpoints.between('sm', 'xl') // '@media (min-width:600px)'
    +theme.breakpoints.up('sm') // '@media (min-width:600px)'
    
    -<Hidden smDown>{...}</Hidden> // '@media (min-width:600px)'
    +<Hidden mdDown>{...}</Hidden> // '@media (min-width:600px)'
    
  • The signature of theme.palette.augmentColor helper has changed:

    -theme.palette.augmentColor(red);
    +theme.palette.augmentColor({ color: red, name: 'brand' });
    

Upgrade helper

For a smoother transition, the adaptV4Theme helper allows you to iteratively upgrade to the new theme structure.

-import { createMuiTheme } from '@material-ui/core/styles';
+import { createMuiTheme, adaptV4Theme } from '@material-ui/core/styles';

-const theme = createMuiTheme({
+const theme = createMuiTheme(adaptV4Theme({
  // v4 theme
-});
+}));

The following changes are supported by the adapter.

Changes

  • The "gutters" abstraction hasn't proven to be used frequently enough to be valuable.

    -theme.mixins.gutters(),
    +paddingLeft: theme.spacing(2),
    +paddingRight: theme.spacing(2),
    +[theme.breakpoints.up('sm')]: {
    +  paddingLeft: theme.spacing(3),
    +  paddingRight: theme.spacing(3),
    +},
    
  • theme.spacing now returns single values with px units by default. This change improves the integration with styled-components & emotion.

    Before:

    theme.spacing(2) => 16
    

    After:

    theme.spacing(2) => '16px'
    
  • The theme.palette.type was renamed to theme.palette.mode, to better follow the "dark mode" term that is usually used for describing this feature.

    import { createMuiTheme } from '@material-ui/core/styles';
    -const theme = createMuiTheme({palette: { type: 'dark' }}),
    +const theme = createMuiTheme({palette: { mode: 'dark' }}),
    
  • The theme.palette.text.hint key was unused in Material-UI components, and has been removed. If you depend on it, you can add it back:

    import { createMuiTheme } from '@material-ui/core/styles';
    
    -const theme = createMuiTheme(),
    +const theme = createMuiTheme({
    +  palette: { text: { hint: 'rgba(0, 0, 0, 0.38)' } },
    +});
    
  • The components' definition inside the theme were restructure under the components key, to allow people easier discoverability about the definitions regarding one component.

  1. props
import { createMuiTheme } from '@material-ui/core/styles';

const theme = createMuiTheme({
-  props: {
-    MuiButton: {
-      disableRipple: true,
-    },
-  },
+  components: {
+    MuiButton: {
+      defaultProps: {
+        disableRipple: true,
+      },
+    },
+  },
});
  1. переопределение
import { createMuiTheme } from '@material-ui/core/styles';

const theme = createMuiTheme({
-  overrides: {
-    MuiButton: {
-      root: { padding: 0 },
-    },
-  },
+  components: {
+    MuiButton: {
+      styleOverrides: {
+        root: { padding: 0 },
+      },
+    },
+  },
});

Стили

  • Renamed fade to alpha to better describe its functionality. The previous name was leading to confusion when the input color already had an alpha value. The helper overrides the alpha value of the color.
- import { fade } from '@material-ui/core/styles';
+ import { alpha } from '@material-ui/core/styles';

const classes = makeStyles(theme => ({
-  backgroundColor: fade(theme.palette.primary.main, theme.palette.action.selectedOpacity),
+  backgroundColor: alpha(theme.palette.primary.main, theme.palette.action.selectedOpacity),
}));

Система

  • The following system functions (and properties) were renamed, because they are considered deprecated CSS:
  1. gridGap to gap
  2. gridColumnGap to columnGap
  3. gridRowGap to rowGap

Core components

As the core components use emotion as a styled engine, the props used by emotion are not intercepted. The prop as in the following codesnippet will not be propagated to the SomeOtherComponent.

<MuiComponent component={SomeOtherComponent} as="button" />

AppBar

  • [AppBar] Remove z-index when position static and relative

Alert

  • Перемещаем компонент из lab в core. Компонент теперь стабилен.

    -import Alert from '@material-ui/lab/Alert';
    -import AlertTitle from '@material-ui/lab/AlertTitle';
    +import Alert from '@material-ui/core/Alert';
    +import AlertTitle from '@material-ui/core/AlertTitle';
    

    You can use the moved-lab-modules codemod for automatic migration.

Autocomplete (Автодополнение)

  • Перемещаем компонент из lab в core. Компонент теперь стабилен.

    -import Autocomplete from '@material-ui/lab/Autocomplete';
    -import useAutocomplete  from '@material-ui/lab/useAutocomplete';
    +import Autocomplete from '@material-ui/core/Autocomplete';
    +import useAutoComplete from '@material-ui/core/useAutocomplete';
    

    You can use our moved-lab-modules codemod for automatic migration.

  • Remove debug prop. There are a couple of simpler alternatives: open={true}, Chrome devtools "Emulate focused", or React devtools prop setter.

  • renderOption should now return the full DOM structure of the option. It makes customizations easier. You can recover from the change with:

    <Autocomplete
    - renderOption={(option, { selected }) => (
    -   <React.Fragment>
    + renderOption={(props, option, { selected }) => (
    +   <li {...props}>
          <Checkbox
            icon={icon}
            checkedIcon={checkedIcon}
            style={{ marginRight: 8 }}
            checked={selected}
          />
          {option.title}
    -   </React.Fragment>
    +   </li>
      )}
    />
    
  • Rename closeIcon prop with clearIcon to avoid confusion.

    -<Autocomplete closeIcon={defaultClearIcon} />
    +<Autocomplete clearIcon={defaultClearIcon} />
    

Avatar

  • Переименовываем circle в circular для единообразия. The possible values should be adjectives, not nouns:

    -<Avatar variant="circle">
    -<Avatar classes={{ circle: 'className' }}>
    +<Avatar variant="circular">
    +<Avatar classes={{ circular: 'className' }}>
    
  • Move the AvatarGroup from the lab to the core.

    -import AvatarGroup from '@material-ui/lab/AvatarGroup';
    +import AvatarGroup from '@material-ui/core/AvatarGroup';
    

Badge

  • Переименовываем circle в circular и rectangle в rectangular для единообразия. The possible values should be adjectives, not nouns:

    -<Badge overlap="circle">
    -<Badge overlap="rectangle">
    +<Badge overlap="circular">
    +<Badge overlap="rectangular">
    <Badge classes={{
    - anchorOriginTopRightRectangle: 'className'
    - anchorOriginBottomRightRectangle: 'className'
    - anchorOriginTopLeftRectangle: 'className'
    - anchorOriginBottomLeftRectangle: 'className'
    - anchorOriginTopRightCircle: 'className'
    - anchorOriginBottomRightCircle: 'className'
    - anchorOriginTopLeftCircle: 'className'
    + anchorOriginTopRightRectangular: 'className'
    + anchorOriginBottomRightRectangular: 'className'
    + anchorOriginTopLeftRectangular: 'className'
    + anchorOriginBottomLeftRectangular: 'className'
    + anchorOriginTopRightCircular: 'className'
    + anchorOriginBottomRightCircular: 'className'
    + anchorOriginTopLeftCircular: 'className'
    }}>
    

BottomNavigation

  • TypeScript: тип параметра event в onChange теперь не React.ChangeEvent а React.SyntheticEvent.

    -<BottomNavigation onChange={(event: React.ChangeEvent<{}>) => {}} />
    +<BottomNavigation onChange={(event: React.SyntheticEvent) => {}} />
    

Box

  • The system props have been deprecated in v5, and replaced with the sx prop.

    -<Box border="1px dashed grey" p={[2, 3, 4]} m={2}>
    +<Box sx={{ border: "1px dashed grey", p: [2, 3, 4], m: 2 }}>
    

    This codemod will automatically update your code to the new syntax. You can read this section for the why behind the change of API.

  • The borderRadius system prop value transformation has been changed. If it receives a number, it multiplies this value with the theme.shape.borderRadius value. Use a string to provide an explicit value, in px.

    -<Box sx={{ borderRadius: 'borderRadius' }}>
    +<Box sx={{ borderRadius: 1 }}>
    
    -<Box sx={{ borderRadius: 16 }}>
    +<Box sx={{ borderRadius: '16px' }}>
    
  • The following properties were renamed, because they are considered deprecated CSS proeprties:

  1. gridGap to gap
  2. gridColumnGap to columnGap
  3. gridRowGap to rowGap
-<Box gridGap="10px">
+<Box sx={{ gap: '10px' }}>
-<Box gridColumnGap="10px" gridRowGap="20px">
+<Box sx={{ columnGap: '10px', rowGap: '20px' }}>

Button

  • Свойство color у кнопки теперь "primary" по умолчанию, а опция "default" удалена. За счет этого кнопка становится ближе к спецификации Material Design, а API становится проще.

    -<Button color="primary" />
    -<Button color="default" />
    +<Button />
    +<Button />
    

Chip

  • Переименовываем вариант default на filled для единообразия.
    -<Chip variant="default">
    +<Chip variant="filled">
    

Групповой прогресс

  • Вариант static объединен с вариантом determinate, и последний подразумевает внешний вид первого. Удаленный вариант редко был полезен. Это было исключением из Material Design и удалено из спецификации.

    -<CircularProgress variant="determinate" />
    
    -<CircularProgress variant="static" classes={{ static: 'className' }} />
    +<CircularProgress variant="determinate" classes={{ determinate: 'className' }} />
    

NB: If you had previously customized determinate, your customizations are probably no longer valid. Please remove them.

Collapse

  • Свойство collapsedHeight переименовано в collapsedSize для поддержки горизонтального направления.

    -<Collapse collapsedHeight={40}>
    +<Collapse collapsedSize={40}>
    
  • Ключ classes.container был изменен для соответствия соглашениям других компонентов.

    -<Collapse classes={{ container: 'collapse' }}>
    +<Collapse classes={{ root: 'collapse' }}>
    

CssBaseline

  • The component was migrated to use the @material-ui/styled-engine (emotion or styled-components) instead of jss. You should remove the @global key when defining the style overrides for it.

    const theme = createMuiTheme({
      components: {
        MuiCssBaseline: {
          styleOverrides: {
    -       '@global': {
              html: {
                WebkitFontSmoothing: 'auto',
              },
    -       },
          },
        },
      },
    });
    
  • The body font size has changed from theme.typography.body2 (0.875rem) to theme.typography.body1 (1rem). To return to the previous size, you can override it in the theme:

    const theme = createMuiTheme({
      typography: {
        body1: {
          fontSize: '0.875rem',
        },
      },
    });
    

    (Note that this will also affect use of the Typography component with the default body1 variant).

Dialog

  • Свойства onE* transition были удалены. Используйте вместо них TransitionProps.

    <Dialog
    -  onEnter={onEnter}
    -  onEntered={onEntered},
    -  onEntering={onEntered},
    -  onExit={onEntered},
    -  onExited={onEntered},
    -  onExiting={onEntered}
    +  TransitionProps={{
    +    onEnter,
    +    onEntered,
    +    onEntering,
    +    onExit,
    +    onExited,
    +    onExiting,
    +  }}
    />
    
  • Remove the disableBackdropClick prop because redundant. Ignore close events from onClose when reason === 'backdropClick' instead.

    <Dialog
    - disableBackdropClick
    - onClose={handleClose}
    + onClose={(event, reason) => {
    +   if (reason !== 'backdropClick') {
    +     onClose(event, reason);
    +   }
    + }}
    />
    
  • [withMobileDialog] Remove this higher-order component. The hook API allows a simpler and more flexible solution:

    -import withMobileDialog from '@material-ui/core/withMobileDialog';
    +import { useTheme, useMediaQuery } from '@material-ui/core';
    
    function ResponsiveDialog(props) {
    - const { fullScreen } = props;
    + const theme = useTheme();
    + const fullScreen = useMediaQuery(theme.breakpoints.down('sm'));
      const [open, setOpen] = React.useState(false);
    
    // ...
    
    -export default withMobileDialog()(ResponsiveDialog);
    +export default ResponsiveDialog;
    

Divider

  • Используем рамку вместо цвета фона. Это предотвращает колебания высоты на масштабированных экранах. Для тех кто настраивает цвет контура, данное изменение требует корректировки переопределения CSS свойства:

    .MuiDivider-root {
    - background-color: #f00;
    + border-color: #f00;
    }
    

ExpansionPanel

  • Переименовываем компоненты ExpansionPanel в Accordion для соответствия наиболее распространенным соглашениям:

    -import ExpansionPanel from '@material-ui/core/ExpansionPanel';
    -import ExpansionPanelSummary from '@material-ui/core/ExpansionPanelSummary';
    -import ExpansionPanelDetails from '@material-ui/core/ExpansionPanelDetails';
    -import ExpansionPanelActions from '@material-ui/core/ExpansionPanelActions';
    +import Accordion from '@material-ui/core/Accordion';
    +import AccordionSummary from '@material-ui/core/AccordionSummary';
    +import AccordionDetails from '@material-ui/core/AccordionDetails';
    +import AccordionActions from '@material-ui/core/AccordionActions';
    
    -<ExpansionPanel>
    +<Accordion>
    -  <ExpansionPanelSummary>
    +  <AccordionSummary>
         <Typography>Location</Typography>
         <Typography>Select trip destination</Typography>
    -  </ExpansionPanelSummary>
    +  </AccordionSummary>
    -  <ExpansionPanelDetails>
    +  <AccordionDetails>
         <Chip label="Barbados" onDelete={() => {}} />
         <Typography variant="caption">Select your destination of choice</Typography>
    -  </ExpansionPanelDetails>
    +  </AccordionDetails>
       <Divider />
    -  <ExpansionPanelActions>
    +  <AccordionActions>
         <Button size="small">Cancel</Button>
         <Button size="small">Save</Button>
    -  </ExpansionPanelActions>
    +  </AccordionActions>
    -</ExpansionPanel>
    +</Accordion>
    
  • TypeScript: тип параметра event в onChange теперь не React.ChangeEvent а React.SyntheticEvent.

    -<Accordion onChange={(event: React.ChangeEvent<{}>, expanded: boolean) => {}} />
    +<Accordion onChange={(event: React.SyntheticEvent, expanded: boolean) => {}} />
    
  • Переименовываем focused в focusVisible для единообразия:

    <Accordion
      classes={{
    -    focused: 'custom-focus-visible-classname',
    +    focusVisible: 'custom-focus-visible-classname',
      }}
    />
    
  • Удаляем display: flex из AccordionDetails, так как он навязывает определенный вид компоновки. Most developers expect a display block.

  • Удаляем свойство IconButtonProps из AccordionSummary. При отрисовке этого компонента вместо IconButton используется элемент <div>. Данное свойство больше не требуется.

Fab

  • Переименовываем round в circular для единообразия. The possible values should be adjectives, not nouns:

    -<Fab variant="round">
    +<Fab variant="circular">
    

Grid

  • Переименовываем свойство justify на justifyContent для согласованности с названием CSS свойства.

    -<Grid justify="center">
    +<Grid justifyContent="center">
    

GridList

  • Переименовываем компоненты GridList на ImageList для согласованности с текущими наименованиями Material Design.

  • Переименовываем GridList свойство spacing на gap для соответствия CSS атрибуту.

  • Переименовываем GridList свойство cellHeight в rowHieght.

  • Добавляем в GridList свойство variant.

  • Переименовываем GridListItemBar свойство actionPosition в position. (Обратите внимание, что соответствующее имя класса также изменяется.)

  • Используем CSS object-fit. For IE11 support either use a polyfill such as https://www.npmjs.com/package/object-fit-images, or continue to use the v4 component.

    -import GridList from '@material-ui/core/GridList';
    -import GridListTile from '@material-ui/core/GridListTile';
    -import GridListTileBar from '@material-ui/core/GridListTileBar';
    +import ImageList from '@material-ui/core/ImageList';
    +import ImageListItem from '@material-ui/core/ImageListItem';
    +import ImageListItemBar from '@material-ui/core/ImageListItemBar';
    
    -<GridList spacing={8} cellHeight={200}>
    -  <GridListTile>
    +<ImageList gap={8} rowHeight={200}>
    +  <ImageListItem>
        <img src="file.jpg" alt="Image title" />
    -    <GridListTileBar
    +    <ImageListItemBar
          title="Title"
          subtitle="Subtitle"
        />
    -  </GridListTile>
    -</GridList>
    +  </ImageListItem>
    +</ImageList>
    

Icon

  • The default value of fontSize was changed from default to medium for consistency. In the unlikey event that you were using the value default, the prop can be removed:

    -<Icon fontSize="default">icon-name</Icon>
    +<Icon>icon-name</Icon>
    

Menu

  • Свойства onE* transition были удалены. Используйте вместо них TransitionProps.

    <Menu
    -  onEnter={onEnter}
    -  onEntered={onEntered},
    -  onEntering={onEntered},
    -  onExit={onEntered},
    -  onExited={onEntered},
    -  onExiting={onEntered}
    +  TransitionProps={{
    +    onEnter,
    +    onEntered,
    +    onEntering,
    +    onExit,
    +    onExited,
    +    onExiting,
    +  }}
    >
    

Modal

  • Remove the disableBackdropClick prop because redundant. Ignore close events from onClose when reason === 'backdropClick' instead.

    <Modal
    - disableBackdropClick
    - onClose={handleClose}
    + onClose={(event, reason) => {
    +   if (reason !== 'backdropClick') {
    +     onClose(event, reason);
    +   }
    + }}
    />
    
  • Remove the onEscapeKeyDown prop because redundant. Use onClose with reason === "escapeKeyDown" instead.

    <Modal
    - onEscapeKeyDown={handleEscapeKeyDown}
    + onClose={(event, reason) => {
    +   if (reason === 'escapeKeyDown') {
    +     handleEscapeKeyDown(event);
    +   }
    + }}
    />
    
  • Удаляем свойство onRendered. В зависимости от варианта использования либо используйте обратную ссылку на дочерний элемент либо хук эффекта в дочернем компоненте.

Pagination

  • Перемещаем компонент из lab в core. Компонент теперь стабилен.

    -import Pagination from '@material-ui/lab/Pagination';
    -import PaginationItem from '@material-ui/lab/PaginationItem';
    -import { usePagination } from '@material-ui/lab/Pagination';
    +import Pagination from '@material-ui/core/Pagination';
    +import PaginationItem from '@material-ui/core/PaginationItem';
    +import usePagination from '@material-ui/core/usePagination';
    

    You can use our moved-lab-modules codemod for automatic migration.

  • Переименовываем round в circular для единообразия. The possible values should be adjectives, not nouns:

    -<Pagination shape="round">
    -<PaginationItem shape="round">
    +<Pagination shape="circular">
    +<PaginationItem shape="circular">
    

Popover

  • Свойства onE* transition были удалены. Используйте вместо них TransitionProps.

    <Popover
    -  onEnter={onEnter}
    -  onEntered={onEntered},
    -  onEntering={onEntered},
    -  onExit={onEntered},
    -  onExited={onEntered},
    -  onExiting={onEntered}
    +  TransitionProps={{
    +    onEnter,
    +    onEntered,
    +    onEntering,
    +    onExit,
    +    onExited,
    +    onExiting,
    +  }}
    />
    

Popper

  • Upgrade Popper.js from v1 to v2. This third-party library has introduced a lot of changes.
    You can read their migration guide or the following summary:

    • The CSS prefixes have changed:

      popper: {
        zIndex: 1,
      - '&[x-placement*="bottom"] $arrow': {
      + '&[data-popper-placement*="bottom"] $arrow': {
      
    • Method names have changed.

      -popperRef.current.scheduleUpdate()
      +popperRef.current.update()
      
      -popperRef.current.update()
      +popperRef.current.forceUpdate()
      
    • Modifiers' API has changed a lot. There are too many changes to be covered here.

Portal

  • Удаляем свойство onRendered. В зависимости от варианта использования либо используйте обратную ссылку на дочерний элемент либо хук эффекта в дочернем компоненте.

Rating

  • Перемещаем компонент из lab в core. Компонент теперь стабилен.

    -import Rating from '@material-ui/lab/Rating';
    +import Rating from '@material-ui/core/Rating';
    

    You can use our moved-lab-modules codemod for automatic migration.

  • Чтобы улучшить доступность изменяем используемую по умолчанию пустую иконку. Если у вас есть свой значок (icon), но нет пустого значка (emptyIcon), вы можете восстановить прежнее поведение с помощью:

    <Rating
      icon={customIcon}
    + emptyIcon={null}
    />
    
  • Переименовываем visuallyhidden в visuallyHidden для единообразия:

    <Rating
      classes={{
    -    visuallyhidden: 'custom-visually-hidden-classname',
    +    visuallyHidden: 'custom-visually-hidden-classname',
      }}
    />
    

RootRef

  • Этот компонент был удален. Ссылку на лежащий в основе наших компонентов DOM узел вы можете получить через ref. Компонент основывался на ReactDOM.findDOMNode, использование которого порицается в React.StrictMode.

    -<RootRef rootRef={ref}>
    -  <Button />
    -</RootRef>
    +<Button ref={ref} />
    

Skeleton

  • Перемещаем компонент из lab в core. Компонент теперь стабилен.

    -import Skeleton from '@material-ui/lab/Skeleton';
    +import Skeleton from '@material-ui/core/Skeleton';
    

    You can use our moved-lab-modules codemod for automatic migration.

  • Переименовываем circle в circular и rect в rectangular для единообразия. The possible values should be adjectives, not nouns:

    -<Skeleton variant="circle" />
    -<Skeleton variant="rect" />
    -<Skeleton classes={{ circle: 'custom-circle-classname', rect: 'custom-rect-classname',  }} />
    +<Skeleton variant="circular" />
    +<Skeleton variant="rectangular" />
    +<Skeleton classes={{ circular: 'custom-circle-classname', rectangular: 'custom-rect-classname',  }} />
    

Slider

  • TypeScript: тип параметра event в onChange теперь не React.ChangeEvent а React.SyntheticEvent.

    -<Slider onChange={(event: React.ChangeEvent<{}>, value: unknown) => {}} />
    +<Slider onChange={(event: React.SyntheticEvent, value: unknown) => {}} />
    
  • The ValueLabelComponent prop is now part of the components prop.

    -<Slider ValueLabelComponent={CustomValueLabel} />
    +<Slider components={{ ValueLabel: CustomValueLabel }} />
    
  • The ThumbComponent prop is not part of the components prop.

    -<Slider ThumbComponent={CustomThumb} />
    +<Slider components={{ Thumb: CustomThumb }} />
    

Snackbar

  • Уведомление теперь отображается в левом нижнем углу на больших экранах. Это лучше соответствует поведению Gmail, Google Keep, material.io и т.д. Вы можете восстановить прежнее поведение с помощью: Вы можете восстановить прежнее поведение с помощью:

    -<Snackbar />
    +<Snackbar anchorOrigin={{ vertical: 'bottom', horizontal: 'center' }} />
    
  • Свойства onE* transition были удалены. Используйте вместо них TransitionProps.

    <Snackbar
    -  onEnter={onEnter}
    -  onEntered={onEntered},
    -  onEntering={onEntered},
    -  onExit={onEntered},
    -  onExited={onEntered},
    -  onExiting={onEntered}
    +  TransitionProps={{
    +    onEnter,
    +    onEntered,
    +    onEntering,
    +    onExit,
    +    onExited,
    +    onExiting,
    +  }}
    />
    

SpeedDial

  • Перемещаем компонент из lab в core. Компонент теперь стабилен.

    -import SpeedDial from '@material-ui/lab/SpeedDial';
    -import SpeedDialAction from '@material-ui/lab/SpeedDialAction';
    -import SpeedDialIcon from '@material-ui/lab/SpeedDialIcon';
    +import SpeedDial from '@material-ui/core/SpeedDial';
    +import SpeedDialAction from '@material-ui/core/SpeedDialAction';
    +import SpeedDialIcon from '@material-ui/core/SpeedDialIcon';
    

    You can use our moved-lab-modules codemod for automatic migration.

Stepper

  • Корневой компонент (Paper) заменен на div. Свойство elevation удалено и Stepper больше не наследует свойста от Paper. Это изменение рассчитано на поощрение композиции.

    -<Stepper elevation={2}>
    -  <Step>
    -    <StepLabel>Hello world</StepLabel>
    -  </Step>
    -</Stepper>
    +<Paper square elevation={2}>
    +  <Stepper>
    +    <Step>
    +      <StepLabel>Hello world</StepLabel>
    +    </Step>
    +  </Stepper>
    +<Paper>
    
  • Удаляем встроенные отступы(padding) 24px.

    -<Stepper>
    -  <Step>
    -    <StepLabel>Hello world</StepLabel>
    -  </Step>
    -</Stepper>
    +<Stepper style={{ padding: 24 }}>
    +  <Step>
    +    <StepLabel>Hello world</StepLabel>
    +  </Step>
    +</Stepper>
    

SvgIcon

  • The default value of fontSize was changed from default to medium for consistency. In the unlikey event that you were using the value default, the prop can be removed:

    -<SvgIcon fontSize="default">
    +<SvgIcon>
      <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />
    </SvgIcon>
    

Table (tаблица)

  • Настройка ярлыков кнопок постраничной разбивки должна осуществляться с помощью свойства getItemAriaLabel. За счет этого улучшается сопоставимость с компонентом Pagination.

    <TablePagination
    - backIconButtonText="Предыдущая"
    - nextIconButtonText="Следующая"
    + getItemAriaLabel={…}
    
  • Переименовываем onChangeRowsPerPage на onRowsPerPageChange и onChangePage на onPageChange для сопоставимоти с API.

    <TablePagination
    - onChangeRowsPerPage={()=>{}}
    - onChangePage={()=>{}}
    + onRowsPerPageChange={()=>{}}
    + onPageChange={()=>{}}
    

Вкладки

  • TypeScript: тип параметра event в onChange теперь не React.ChangeEvent а React.SyntheticEvent.

    -<Tabs onChange={(event: React.ChangeEvent<{}>, value: unknown) => {}} />
    +<Tabs onChange={(event: React.SyntheticEvent, value: unknown) => {}} />
    
  • Управляющее кнопками прокрутки API разделено на два параметра.

    • Параметр scrollButtons управляет видимостью кнопок в зависимоти от доступного пространства.
    • Параметр allowScrollButtonsMobile удаляет медиа-запрос CSS, который систематически скрывает кнопки прокрутки на мобильных устройствах.
    -<Tabs scrollButtons="on" />
    -<Tabs scrollButtons="desktop" />
    -<Tabs scrollButtons="off" />
    +<Tabs scrollButtons allowScrollButtonsMobile />
    +<Tabs scrollButtons />
    +<Tabs scrollButtons={false} />
    

TextField

  • Change the default variant from standard to outlined. Standard has been removed from the Material Design Guidelines.

    -<TextField value="Standard" />
    -<TextField value="Outlined" variant="outlined" />
    +<TextField value="Standard" variant="standard" />
    +<TextField value="Outlined" />
    

This codemod will automatically update your code.

  • Rename rowsMax prop with maxRows for consistency with HTML attributes.

    -<TextField rowsMax={6}>
    +<TextField maxRows={6}>
    
  • Улучшаем определение поведения - когда используется textarea фиксированной высоты, а когда textarea c динамической высотой. Вам нужно использовать параметр minRows в следующем случае:

    -<TextField rows={2} maxRows={5} />
    +<TextField minRows={2} maxRows={5} />
    
  • Change ref forwarding expectations on custom inputComponent. The component should forward the ref prop instead of the inputRef prop.

    -function NumberFormatCustom(props) {
    -  const { inputRef, onChange, ...other } = props;
    +const NumberFormatCustom = React.forwardRef(function NumberFormatCustom(
    +  props,
    +  ref,
    +) {
      const { onChange, ...other } = props;
    
      return (
        <NumberFormat
          {...other}
    -     getInputRef={inputRef}
    +     getInputRef={ref}
    
  • Rename marginDense and inputMarginDense classes to sizeSmall and inputSizeSmall to match the prop.

    -<Input margin="dense" />
    +<Input size="small" />
    

TextareaAutosize

  • Удаляем свойство rows и используем вместо него minRows. Цель этого изменения - сделать поведение свойства более понятным.

    -<TextareaAutosize rows={2} />
    +<TextareaAutosize minRows={2} />
    
  • Rename rowsMax prop with maxRows for consistency with HTML attributes.

    -<TextareAutosize rowsMax={6}>
    +<TextareAutosize maxRows={6}>
    
  • Переименовываем свойство rowsMin на minRows для соответствия HTML атрибутам.

    -<TextareAutosize rowsMin={1}>
    +<TextareAutosize minRows={1}>
    

ToggleButton

  • Перемещаем компонент из lab в core. Компонент теперь стабилен.

    -import ToggleButton from '@material-ui/lab/ToggleButton';
    -import ToggleButtonGroup from '@material-ui/lab/ToggleButtonGroup';
    +import ToggleButton from '@material-ui/core/ToggleButton';
    +import ToggleButtonGroup from '@material-ui/core/ToggleButtonGroup';
    

    You can use our moved-lab-modules codemod for automatic migration.

Tooltip

  • Подсказки теперь интерактивны по умолчанию.

    Прежнее подразумеваемое по умолчанию поведение не удовлетворяет требованию success criterion 1.4.3 ("hoverable") в WCAG 2.1. Чтобы отразить новое значение по умолчанию, прежнее свойство переименовано на disableInteractive. Если вы хотите восстановить прежнее поведение (лишившись при этом уровня АА), вы можете применить следующие изменения:

    -<Tooltip>
    +<Tooltip disableInteractive>
    
    # Интерактивные подсказки больше не нуждаются в свойстве `interactive`.
    -<Tooltip interactive>
    +<Tooltip>
    

Typography

  • Заменяем свойство srOnly, чтобы не дублировать возможности System:

    -import Typography from '@material-ui/core/Typography';
    +import { visuallyHidden } from '@material-ui/system';
    +import styled from 'styled-component';
    
    +const Span = styled('span')(visuallyHidden);
    
    -<Typography variant="srOnly">Create a user</Typography>
    +<Span>Create a user</Span>
    

Система

  • Replace css prop with sx to avoid collision with styled-components & emotion CSS props.
-<Box css={{ color: 'primary.main' }} />
+<Box sx={{ color: 'primary.main' }} />