Flutter Material UI Migration Guide

If your Flutter app still imports package/material.dart or package/cupertino.dart, it's time to understand the new standalone UI packages. Flutter has moved Material and Cupertino into separate packages on pub.dev, allowing them to evolve independently of the Flutter SDK.
The migration is designed to preserve existing widget behavior, but third-party dependencies can make the process more complicated.
Here's how to migrate your project, update localization, handle legacy dependencies, and avoid common compatibility issues.

---

🚀 Why Flutter Is Moving Material and Cupertino Into Separate Packages​

Flutter's Material and Cupertino libraries are now available as standalone packages:

• 📦 Material UI: material_ui
• 🍎 Cupertino UI: cupertino_ui

Previously, these libraries were bundled directly into the Flutter SDK. Moving them into separate packages allows the Flutter team to maintain and update them independently.

This change brings several benefits:

• ⚡ Faster updates: UI improvements and bug fixes can ship without waiting for a new Flutter SDK release.
• 🔧 More flexible upgrades: You can update your UI packages independently of the framework.
• 🛡️ A smoother migration: Version 1.0.0 started from code that matches the existing framework libraries, helping preserve current behavior.
• 📅 Independent development: The packages can evolve on their own release schedules.

The original SDK libraries are planned for deprecation. Migrating helps your project stay aligned with ongoing development.

---

🛠️ How to Migrate a Flutter Project​

The migration is straightforward for many applications. You can use Dart's automated fix to update your imports and add the required package dependencies.

Step 1: Add the Required Packages​

Run the following command to add the Material UI package:

flutter pub add material_ui

If your project directly uses Cupertino widgets, add that package too:

flutter pub add cupertino_ui

You only need to add the packages your application uses directly. Review your imports before deciding which dependencies to add.

Step 2: Update Your Imports Automatically​

Run Dart's migration fix:

dart fix --apply --code=migrate_design_widgets

This fix updates imports from the old SDK libraries to the standalone packages.

For example, the Material import changes from:

import 'package/material.dart';

To:

import 'package/material_ui.dart';

The Cupertino import changes from:

import 'package/cupertino.dart';

To:

import 'package/cupertino_ui.dart';

If the migration fix reports missing dependencies or leaves imports unresolved, add the required packages and run the fix again.

Step 3: Check and Test Your Application​

After migrating, review the changes and run your tests.

flutter pub get
flutter analyze
flutter test

Also, run the app on the platforms you support. Pay special attention to themes, localization, navigation, dialogs, and widgets supplied by third-party packages.
Don't assume the migration is complete just because the imports have changed successfully.

---

🌍 How to Update Flutter Localization​

The standalone packages provide their own localization support. If your application previously used the global Material and Cupertino delegates from flutter_localizations, review that setup during migration.
For a typical Material application, you can use:

MaterialApp(
localizationsDelegates: GlobalMaterialLocalizations.delegates,
)

The standalone Material package provides a combined delegate list for the framework's widgets and Material and Cupertino localization support.
Make sure your project imports the appropriate localization classes from the new packages and removes outdated imports or configuration that are no longer needed. If you use custom localization delegates, keep them configured as required by your application.

---

🔌 Handling Third-Party Packages That Still Use the Old Imports​

One of the biggest migration challenges is a dependency that still uses the original Flutter Material or Cupertino libraries.
For example, your application may use a UI package that hasn't migrated yet. Even if your own code uses material_ui, the dependency may still expect widgets and theme data from package/material.dart.
For compatible Material dependencies, you can use MaterialUiCompatibilityBridge to pass theme and localization information into the legacy widget tree.

Configure it inside MaterialApp.builder:

MaterialApp(
builder: (context, child) =>
MaterialUiCompatibilityBridge(child: child!),
)

This bridge helps legacy widgets access information such as:

• Theme.of(context)
• MaterialLocalizations.of(context)

However, the bridge does not solve every compatibility problem.

⚠️ Important Limitations of the Compatibility Bridge​

Dart treats types imported from the old SDK library and the standalone package as different types, even when their names are identical.
For example, a dependency may expose ColorScheme or TextTheme in its public API. If that dependency expects the old type while your application passes the corresponding type from material_ui, the code may fail to compile.
The bridge does not fix these public API type mismatches.

If you encounter this problem, you may need to:

1. Update the dependency to a version that supports the standalone packages.
2. Migrate the dependency yourself if you maintain it.
3. Choose an alternative package if the existing dependency cannot be updated.

If your application uses Cupertino widgets from legacy dependencies, check the corresponding CupertinoUiCompatibilityBridge and its requirements.

---

📦 What Package Authors Need to Know​

If you publish Flutter packages on pub.dev, this migration requires extra care.
Changing public APIs from framework types to standalone package types can break existing consumers. For example, a package that previously accepted a ColorScheme from package/material.dart may no longer accept the equivalent type from material_ui.

Before releasing a migration:

• Review public method parameters, return types, and callback signatures.
• Check your dependencies and example applications.
• Run tests against the migrated packages.
• Document any required changes for users.

If the change breaks compatibility with existing consumers, release it as a new major version under semantic versioning.

---

✅ Flutter Migration Checklist​

Before merging your changes, make sure you have completed these steps:

• Add the required standalone UI packages.
• Update Material and Cupertino imports.
• Review localization configuration.
• Identify dependencies that still use the old SDK libraries.
• Check for incompatible public API types.
• Run flutter analyze and your test suite.
• Test the application on your supported platforms.
• Review the changes before merging them into your main branch.
  

---

💡 Final Recommendation​

For most applications, migrating to material_ui and cupertino_ui is a manageable change. The automated migration fix handles much of the import work, while the main risk comes from third-party packages that still depend on the original SDK types.
The safest approach is to migrate on a separate Git branch, inspect the dependency tree, run your tests, and verify the app before merging.
If a critical dependency hasn't migrated yet, check its public API and release roadmap before making the change. A little preparation can save you from chasing confusing type errors later.

---

Frequently Asked Questions​

-----------------

Do I need to migrate immediately?​

The standalone packages are available now, and the old libraries are planned for deprecation. Check the migration guidance for your Flutter release and plan the change before the old libraries are removed.

Will migrating change how my widgets look?​

The initial standalone package releases were based on the existing framework implementations. However, you should still test your app because dependency compatibility and subsequent package updates can introduce issues.

Can I keep using packages that import the old Material library?​

In some cases, yes. The compatibility bridge can help with theme and localization lookups, but it cannot fix incompatible public API types. Dependencies may need their own migration.

Is the migration breaking for pub.dev packages?​

It can be. If the migration changes public API types in a way that breaks existing consumers, you should publish a major version.

Should I migrate Material and Cupertino together?​

Not necessarily. Migrate the libraries your project uses, and review any transitive or direct dependencies that rely on the old imports. If you use both, check both migration paths.