Breaking changes в v5

MUI v5 принесла значительные изменения по сравнению с версией 4, влияющие на структуру проектов и подходы к стилизации. Эти изменения напрямую затрагивают совместимость и требуют внимательного пересмотра существующего кода при обновлении.

1. Новая система стилизации: @mui/system и styled

В MUI v5 основной акцент сделан на @mui/system и использование функции styled, которая заменяет устаревший makeStyles и withStyles.

  • makeStyles и withStyles теперь считаются устаревшими (deprecated) и в будущем будут полностью удалены. Их использование возможно, но рекомендуется переходить на новую систему.
  • Функция styled позволяет создавать компоненты с инкапсулированными стилями и поддержкой темы:
import { styled } from '@mui/material/styles';
import Button from '@mui/material/Button';

const MyButton = styled(Button)(({ theme }) => ({
  backgroundColor: theme.palette.primary.main,
  color: theme.palette.common.white,
  '&:hover': {
    backgroundColor: theme.palette.primary.dark,
  },
}));

Преимущества новой системы:

  • Полная интеграция с темами и адаптивными стилями.
  • Возможность использовать sx-проп для быстрых инлайн-стилей.
  • Поддержка CSS-переменных и системных функций MUI (spacing, palette, typography).

2. Проп sx и системные свойства

v5 внедрила новый проп sx, который позволяет задавать стили на уровне компонентов без необходимости создавать отдельные классы.

<Box sx={{ display: 'flex', justifyContent: 'center', p: 2 }}>
  Контент по центру
</Box>

Особенности:

  • Поддержка темы (theme.spacing, theme.palette).
  • Возможность передавать массивы для медиазапросов (responsive values):
<Box sx={{ width: ['100%', '50%', '25%'] }}>Адаптивный блок</Box>
  • Совместимость с системными свойствами (margin, padding, color, typography).

3. Изменения в Theme и настройке темы

MUI v5 переработала объект темы:

  • Цветовые палитры теперь строго типизированы. Использование нестандартных ключей в палитре вызывает ошибки TypeScript.
  • Объект theme.shape и theme.spacing остался, но theme.overrides заменен на theme.components:
const theme = createTheme({
  components: {
    MuiButton: {
      styleOverrides: {
        root: {
          borderRadius: 8,
        },
      },
    },
  },
});
  • Поддержка dark/light режимов теперь реализуется через palette.mode.

4. Изменения в названиях компонентов и импортах

  • В v5 рекомендуется импортировать компоненты напрямую из @mui/material, а не через подмодули:
// Старый вариант
import Button from '@material-ui/core/Button';

// Новый вариант
import Button from '@mui/material/Button';
  • Это улучшает tree-shaking и уменьшает размер итогового бандла.

5. Устаревшие API и методы

  • withWidth, useMediaQuery остаются, но withWidth постепенно выходит из употребления.
  • makeStyles, withStyles – deprecated, перенос всех кастомных стилей на styled или sx.
  • theme.overrides заменяется на theme.components.

6. Миграция Typography

Типографика получила улучшенную типизацию и поддержку системных свойств:

<Typography variant="h4" sx={{ mb: 2 }}>
  Заголовок
</Typography>
  • В sx можно указывать адаптивные размеры:
<Typography sx={{ fontSize: { xs: '1rem', sm: '1.5rem' } }}>Текст</Typography>

7. Icons и SVG

  • Импорты иконок изменены:
// Старый вариант
import DeleteIcon from '@material-ui/icons/Delete';

// Новый вариант
import DeleteIcon from '@mui/icons-material/Delete';
  • Рекомендуется использовать пакет @mui/icons-material вместо @material-ui/icons.

8. Обновления Grid и Box

  • Grid теперь полностью поддерживает систему sx и медиазапросы.
  • Проп spacing можно задавать через числа, которые автоматически конвертируются в пиксели по theme.spacing:
<Grid container spacing={2}>
  <Grid item xs={6}>Элемент 1</Grid>
  <Grid item xs={6}>Элемент 2</Grid>
</Grid>
  • Box заменяет многие устаревшие контейнеры и поддерживает любую комбинацию системных свойств.

9. Совместимость с TypeScript

MUI v5 полностью переписана с поддержкой TypeScript:

  • Строгая типизация theme и sx.
  • Прямое использование кастомных палитр требует расширения интерфейса Theme:
declare module '@mui/material/styles' {
  interface Palette {
    customColor: Palette['primary'];
  }
  interface PaletteOptions {
    customColor?: PaletteOptions['primary'];
  }
}

10. Рекомендации при обновлении с v4

  • Заменить все импорты с @material-ui/core и @material-ui/icons на новые пакеты @mui/material и @mui/icons-material.
  • Переписать кастомные стили с makeStyles/withStyles на styled или sx.
  • Пересмотреть объект темы, заменив overrides на components.
  • Проверить адаптивные стили, теперь они лучше поддерживаются через sx и медиазапросы.
  • Обновить типографику и Grid, чтобы использовать возможности адаптивного sx и новых пропсов.

Эти изменения в MUI v5 делают библиотеку более гибкой, модульной и адаптированной к современным подходам к React и TypeScript, но требуют внимательной миграции с v4 для сохранения стабильности проекта.

Оглавление