Migration from v0.x to v1

Yeah, v1 has been released! Take advantage of 2 years worth of effort.

FAQ

Woah - the API is way different! Does that mean 1.0 is completely different, I'll have to learn the basics all over again, and migrating will be practically impossible?

I'm glad you asked! The answer is no. The core concepts haven't changed. You will notice that the API provides more flexibility, but this has a cost – lower-level components that abstract less complexity.

What motivated such a large change?

Material UI was started 4 years ago. The ecosystem has evolved a lot since then, we have also learned a lot. @nathanmarks started an ambitious task, rebuilding Material UI from the ground-up taking advantage of this knowledge to address long-standing issues. To name some of the major changes:

New styling solution using CSS-in-JS (better customization power, better performance)
New theme handling (nesting, self-supporting, etc.)
Blazing fast documentation thanks to Next.js
Way better test coverage (99%+, run on all the major browsers, visual regression tests)
Full server-side rendering support
Wide range of supported browsers

Where should I start in a migration?

Start by installing the v1.x version of Material UI along side the v0.x version.

With yarn:

<span class="token function">yarn</span> <span class="token function">add</span> material-ui
<span class="token function">yarn</span> <span class="token function">add</span> @material-ui/core

Or with npm:

<span class="token function">npm</span> <span class="token function">install</span> material-ui
<span class="token function">npm</span> <span class="token function">install</span> @material-ui/core

then

<span class="token keyword">import</span> FlatButton <span class="token keyword">from</span> <span class="token string">'material-ui/FlatButton'</span><span class="token punctuation">;</span> <span class="token comment">// v0.x</span>
<span class="token keyword">import</span> Button <span class="token keyword">from</span> <span class="token string">'@material-ui/core/Button'</span><span class="token punctuation">;</span> <span class="token comment">// v1.x</span>

Run the migration helper on your project.
MuiThemeProvider is optional for v1.x., but if you have a custom theme, you are free to use v0.x and v1.x versions of the component at the same time, like this:

<span class="token keyword">import</span> <span class="token operator">*</span> <span class="token keyword">as</span> React <span class="token keyword">from</span> <span class="token string">'react'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> MuiThemeProvider<span class="token punctuation">,</span> createMuiTheme <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@material-ui/core/styles'</span><span class="token punctuation">;</span> <span class="token comment">// v1.x</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> MuiThemeProvider <span class="token keyword">as</span> V0MuiThemeProvider <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'material-ui'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> getMuiTheme <span class="token keyword">from</span> <span class="token string">'material-ui/styles/getMuiTheme'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createMuiTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token comment">/* theme for v1.x */</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">const</span> themeV0 <span class="token operator">=</span> <span class="token function">getMuiTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token comment">/* theme for v0.x */</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">MuiThemeProvider</span></span> <span class="token attr-name">theme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>theme<span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
      <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">V0MuiThemeProvider</span></span> <span class="token attr-name">muiTheme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>themeV0<span class="token punctuation">}</span></span><span class="token punctuation">></span></span><span class="token punctuation">{</span><span class="token comment">/*Components*/</span><span class="token punctuation">}</span><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">V0MuiThemeProvider</span></span><span class="token punctuation">></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">MuiThemeProvider</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

<span class="token keyword">export</span> <span class="token keyword">default</span> App<span class="token punctuation">;</span>

After that, you are free to migrate one component instance at the time.

Components

Autocomplete

Material UI doesn't provide a high-level API for solving this problem. You're encouraged you to explore the solutions the React community has built.

In the future, we will look into providing a simple component to solve the simple use cases: #9997.

Svg Icon

Run the migration helper on your project.

This will apply a change such as the following:

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import AddIcon from 'material-ui/svg-icons/Add';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import AddIcon from '@mui/icons-material/Add';
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">&lt;AddIcon /></span></span>

Flat Button

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import FlatButton from 'material-ui/FlatButton';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import Button from '@material-ui/core/Button';
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">&lt;FlatButton />
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">&lt;Button /></span></span>

Raised Button

RaisedButton upgrade path:

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import RaisedButton from 'material-ui/RaisedButton';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import Button from '@material-ui/core/Button';
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">&lt;RaisedButton />
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">&lt;Button variant="contained" /></span></span>

Subheader

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import Subheader from 'material-ui/Subheader';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import ListSubheader from '@material-ui/core/ListSubheader';
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">&lt;Subheader>Sub Heading&lt;/Subheader>
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">&lt;ListSubheader>Sub Heading&lt;/ListSubheader></span></span>

Toggle

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import Toggle from 'material-ui/Toggle';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import Switch from '@material-ui/core/Switch';
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">&lt;Toggle
</span><span class="token prefix deleted">-</span><span class="token line">  toggled={this.state.checkedA}
</span><span class="token prefix deleted">-</span><span class="token line">  onToggle={this.handleToggle}
</span><span class="token prefix deleted">-</span><span class="token line">/>
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">&lt;Switch
</span><span class="token prefix inserted">+</span><span class="token line">  checked={this.state.checkedA}
</span><span class="token prefix inserted">+</span><span class="token line">  onChange={this.handleSwitch}
</span><span class="token prefix inserted">+</span><span class="token line">/></span></span>

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import MenuItem from 'material-ui/MenuItem';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import MenuItem from '@material-ui/core/MenuItem';
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">&lt;MenuItem primaryText="Profile" />
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">&lt;MenuItem>Profile&lt;/MenuItem></span></span>

Font Icon

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import FontIcon from 'material-ui/FontIcon';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import Icon from '@material-ui/core/Icon';
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">&lt;FontIcon>home&lt;/FontIcon>
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">&lt;Icon>home&lt;/Icon></span></span>

Circular Progress

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import CircularProgress from 'material-ui/CircularProgress';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import CircularProgress from '@material-ui/core/CircularProgress';
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">&lt;CircularProgress mode="indeterminate" />
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">&lt;CircularProgress variant="indeterminate" /></span></span>

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import DropDownMenu from 'material-ui/DropDownMenu';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import Select from '@material-ui/core/Select';
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">&lt;DropDownMenu>&lt;/DropDownMenu>
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">&lt;Select value={this.state.value}>&lt;/Select></span></span>

To be continued…

Have you successfully migrated your app, and wish to help the community? There is an open issue in order to finish this migration guide #7195. Any pull request is welcomed 😊.