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?

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

   With yarn:

   yarn add material-ui
   yarn add @material-ui/core

   Or with npm:

   npm install material-ui
   npm install @material-ui/core

   then

   import FlatButton from 'material-ui/FlatButton'; // v0.x
   import Button from '@material-ui/core/Button'; // v1.x

2. Run the migration helper on your project.

3. 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:

   import React from 'react';
   import { MuiThemeProvider, createMuiTheme } from '@material-ui/core/styles'; // v1.x
   import { MuiThemeProvider as V0MuiThemeProvider} from 'material-ui';
   import getMuiTheme from 'material-ui/styles/getMuiTheme';
   
   const theme = createMuiTheme({
    /* theme for v1.x */
   });
   const themeV0 = getMuiTheme({
    /* theme for v0.x */
   });
   
   function App() {
    return (
      <MuiThemeProvider theme={theme}>
        <V0MuiThemeProvider muiTheme={themeV0}>
          {/*Components*/}
        </V0MuiThemeProvider>
      </MuiThemeProvider>
    );
   }
   
   export default App;

4. 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:

-import AddIcon from 'material-ui/svg-icons/Add';
+import AddIcon from '@material-ui/icons/Add';

<AddIcon />

Flat Button

-import FlatButton from 'material-ui/FlatButton';
+import Button from '@material-ui/core/Button';

-<FlatButton />
+<Button />

Raised Button

RaisedButton upgrade path:

-import RaisedButton from 'material-ui/RaisedButton';
+import Button from '@material-ui/core/Button';

-<RaisedButton />
+<Button variant="contained" />

Subheader

-import Subheader from 'material-ui/Subheader';
+import ListSubheader from '@material-ui/core/ListSubheader';

-<Subheader>Sub Heading</Subheader>
+<ListSubheader>Sub Heading</ListSubheader>

Toggle

-import Toggle from 'material-ui/Toggle';
+import Switch from '@material-ui/core/Switch';

-<Toggle
-  toggled={this.state.checkedA}
-  onToggle={this.handleToggle}
-/>
+<Switch
+  checked={this.state.checkedA}
+  onChange={this.handleSwitch}
+/>

Menu Item

-import MenuItem from 'material-ui/MenuItem';
+import MenuItem from '@material-ui/core/MenuItem';

-<MenuItem primaryText="Profile" />
+<MenuItem>Profile</MenuItem>

Font Icon

-import FontIcon from 'material-ui/FontIcon';
+import Icon from '@material-ui/core/Icon';

-<FontIcon>home</FontIcon>
+<Icon>home</Icon>

Circular Progress

-import CircularProgress from 'material-ui/CircularProgress';
+import CircularProgress from '@material-ui/core/CircularProgress';

-<CircularProgress mode="indeterminate" />
+<CircularProgress variant="indeterminate" />

Drop Down Menu

-import DropDownMenu from 'material-ui/DropDownMenu';
+import Select from '@material-ui/core/Select';

-<DropDownMenu></DropDownMenu>
+<Select value={this.state.value}></Select>

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 😊.