Миграция с Material-UI v4

В MUI v5 была проведена реорганизация пакетов. В версии v4 все компоненты импортировались из одного пакета @material-ui/core, тогда как в v5 каждый компонент доступен через основной пакет @mui/material. Это важно учитывать при миграции:

// Material-UI v4
import { Button, TextField } from '@material-ui/core';

// MUI v5
import { Button, TextField } from '@mui/material';

Для иконок вместо @material-ui/icons используется пакет @mui/icons-material:

import DeleteIcon from '@mui/icons-material/Delete';

Кроме того, в v5 появились новые отдельные пакеты для системного API, стилевых утилит и лаб-компонентов (@mui/system, @mui/lab), что позволяет более гибко работать с кастомизацией и экспериментальными компонентами.

Система тем и кастомизация

Система тем в v5 стала более мощной и модульной. Основные изменения:

  1. Функция createTheme теперь полностью совместима с TypeScript.
  2. Поддержка расширяемых палитр — можно добавлять новые цветовые вариации и использовать их через theme.palette.
  3. CSS переменные для тем — компоненты могут автоматически подстраиваться под динамические изменения темы.

Пример создания темы в MUI v5:

import { createTheme, ThemeProvider } from '@mui/material/styles';

const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
    },
    secondary: {
      main: '#dc004e',
    },
    customGreen: {
      main: '#00c853',
      contrastText: '#ffffff',
    },
  },
  typography: {
    fontFamily: 'Roboto, Arial, sans-serif',
  },
});

<ThemeProvider theme={theme}>
  <App />
</ThemeProvider>

Важно учитывать, что старые свойства палитры, которые использовались в v4 (type: 'light' | 'dark'), в v5 заменены на mode: 'light' | 'dark'.

Стилизация компонентов

MUI v5 предлагает три основных подхода к стилизации:

  1. sx проп — мощный способ применять стили прямо на компонент:
<Button sx={{ bgcolor: 'primary.main', color: 'white', '&:hover': { bgcolor: 'primary.dark' } }}>
  Кнопка
</Button>
  1. Функция styled — позволяет создавать полностью кастомные компоненты:
import { styled } from '@mui/material/styles';
import Button from '@mui/material/Button';

const CustomButton = styled(Button)(({ theme }) => ({
  backgroundColor: theme.palette.customGreen.main,
  color: theme.palette.customGreen.contrastText,
  '&:hover': {
    backgroundColor: theme.palette.customGreen.dark,
  },
}));
  1. makeStyles и withStyles — устаревшие API из v4, теперь рекомендуется использовать sx или styled, хотя старый код можно поддерживать через @mui/styles:
import { makeStyles } from '@mui/styles';

const useStyles = makeStyles({
  root: {
    backgroundColor: 'red',
  },
});

@mui/styles в v5 работает только при использовании ThemeProvider из @mui/material/styles, и его использование не рекомендуется для новых проектов.

Работа с Grid и Box

MUI v5 сохраняет совместимость с Flexbox Grid из v4, но добавляет улучшенные возможности через sx и системные свойства:

import { Box, Grid } from '@mui/material';

<Box sx={{ display: 'flex', gap: 2, p: 2 }}>
  <Grid container spacing={2}>
    <Grid item xs={6}>
      Первый блок
    </Grid>
    <Grid item xs={6}>
      Второй блок
    </Grid>
  </Grid>
</Box>

Ключевые изменения:

  • spacing теперь может быть дробным числом (например, spacing={1.5}).
  • Компонент Box стал полноценным универсальным контейнером для системных стилей (margin, padding, display, flex, grid, typography и др.) через sx.

Работа с компонентами формы

Компоненты формы (TextField, Select, Checkbox, Radio) получили обновленные пропсы:

  • variant по умолчанию теперь outlined.
  • FormHelperTextProps и InputProps стали более строгими, улучшена типизация.
  • Компонент Select поддерживает новый API для работы с multiple и controlled значениями.

Пример TextField с кастомным стилем:

<TextField
  label="Email"
  variant="outlined"
  sx={{
    '& .MuiOutlinedInput-root': {
      '& fieldset': {
        borderColor: 'primary.main',
      },
      '&:hover fieldset': {
        borderColor: 'primary.dark',
      },
    },
  }}
/>

Обновление компонентов Lab

Компоненты @mui/lab (DatePicker, Timeline, AlertDialog) были переработаны:

  • Все Date/Time компоненты теперь используют AdapterDateFns или AdapterDayjs вместо устаревших @date-io.
  • Пропсы value и onChange стандартизированы для совместимости с controlled компонентами.
  • Механизм локализации вынесен в отдельный провайдер LocalizationProvider.

Пример использования DatePicker:

import { LocalizationProvider, DatePicker } from '@mui/lab';
import AdapterDateFns from '@mui/lab/AdapterDateFns';

<LocalizationProvider dateAdapter={AdapterDateFns}>
  <DatePicker
    label="Выберите дату"
    value={selectedDate}
    onCha nge={(newValue) => setSelectedDate(newValue)}
    renderInput={(params) => <TextField {...params} />}
  />
</LocalizationProvider>

Переход на Emotion для стилизации

MUI v5 использует Emotion как стандартный движок CSS-in-JS, что обеспечивает:

  • Поддержку вложенных селекторов.
  • Автоматическую генерацию классов без конфликтов.
  • Интеграцию с sx и styled.

Для старых проектов на JSS необходимо подключать пакет @mui/styles или полностью перейти на Emotion.

Адаптация существующего кода

При миграции с v4 на v5 стоит учитывать следующие практические шаги:

  1. Заменить все импорты из @material-ui/core на @mui/material.
  2. Переписать кастомные темы с использованием mode вместо type.
  3. Использовать sx или styled вместо makeStyles.
  4. Обновить компоненты Lab и иконки.
  5. Проверить совместимость типов TypeScript для новых API.

Эти изменения позволяют сохранить функциональность, улучшить поддержку новых возможностей библиотеки и использовать современный подход к стилизации и темам.

Оглавление