Material UI Installation with React 18

When working with React 18, you might encounter dependency conflicts when trying to install Material UI (MUI). This article explains the core issue and provides the recommended solutions.

Problem Overview

The main issue occurs when attempting to install @material-ui/core (MUI v4) with React 18, resulting in the following error:

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! Found: react@18.0.0
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17.0.0" from @material-ui/core@4.12.3

This happens because Material UI v4 has explicit peer dependencies that only support React 16.8+ or 17.0+, but not React 18.

Recommended Solution: Upgrade to MUI v5

The official solution is to migrate to Material UI v5 (now branded as MUI), which fully supports React 18.

Installation

npm

npm install @mui/material @emotion/react @emotion/styled

yarn

yarn add @mui/material @emotion/react @emotion/styled

Icon Package

For icons, use the updated package:

npm install @mui/icons-material

Import Updates

Update your import statements from the old format:

// Old v4 imports (don't use with React 18)
import { makeStyles } from '@material-ui/core/styles';
import Paper from '@material-ui/core/Paper';
import SendIcon from '@material-ui/icons/Send';

To the new MUI v5 format:

// New v5 imports (compatible with React 18)
import { makeStyles } from '@mui/material/styles';
import Paper from '@mui/material/Paper';
import SendIcon from '@mui/icons-material/Send';

Alternative Solutions (Not Recommended)

WARNING

These approaches are generally not recommended for new projects and may cause compatibility issues.

Using --legacy-peer-deps Flag

You can force installation with the legacy peer dependencies flag:

npm install @material-ui/core --legacy-peer-deps

Using --force Flag

Alternatively, use the force flag:

npm install @material-ui/core --force

DANGER

Using --force or --legacy-peer-deps bypasses dependency resolution checks and may result in unexpected behavior or runtime errors. These flags should only be considered for temporary solutions or legacy projects where upgrading isn't feasible.

Downgrading React

Another approach is to downgrade your React version to be compatible with MUI v4:

npm install react@^17.0.0 react-dom@^17.0.0

However, this approach sacrifices React 18 features and is not recommended for new development.

Understanding the Dependency Conflict

Material UI v4 explicitly specifies React compatibility in its peer dependencies:

{
  "react": "^16.8.0 || ^17.0.0",
  "react-dom": "^16.8.0 || ^17.0.0"
}

MUI v5.6.0+ officially supports React 18, with the current latest version offering full compatibility.

Conclusion

For React 18 projects, the recommended approach is:

1. Use MUI v5 (@mui/material) instead of the deprecated @material-ui/core
2. Update import statements to the new package structure
3. Avoid using --force or --legacy-peer-deps flags for production projects

This ensures you benefit from both React 18's new features and MUI's ongoing development and support.