How to Migrate from Flutter Material to the Standalone material_ui Package

Starting with Flutter 3.47, Material and Cupertino design libraries are available as standalone packages on pub.dev. The old package:flutter/material.dart import still works today, but it’s scheduled for formal deprecation in the Fall 2026 stable release. Now is the time to migrate.

This guide covers both the automated dart fix command and manual migration, plus how to handle third-party dependencies that haven’t migrated yet.

Why Migrate?

• Faster updates: material_ui ships weekly on pub.dev, independent of Flutter’s quarterly releases.
• Community contributions: The standalone packages are open for contributions.
• Future-proof: The in-framework Material library will be deprecated and eventually removed.
• Decoupled localizations: flutter_localizations is unbundled; delegates now live in material_ui.

Method 1: Automated Migration with dart fix

The recommended approach uses Dart’s built-in data-driven fix tool.

Step 1: Upgrade Flutter

Ensure you’re on Flutter 3.47 or later:

flutter upgrade

Step 2: Run the Migration Command

dart fix --apply --code=migrate_design_widgets

This single command does two things:

1. Adds material_ui to your pubspec.yaml.
2. Updates all imports from package:flutter/material.dart to package:material_ui/material_ui.dart.

Step 3: Verify

After running the command, search your project for any remaining legacy imports:

grep -r "package:flutter/material.dart" lib/
grep -r "package:flutter/cupertino.dart" lib/

If results appear, run the fix again or update them manually.

Known Issue: pubspec.yaml

If the migration tool fails to update your pubspec.yaml (a known early bug), resolve it manually:

flutter pub add material_ui

Then run the fix again:

dart fix --apply --code=migrate_design_widgets

Method 2: Manual Migration

For more control, or when dart fix doesn’t work for your project structure:

Step 1: Add the Package

# pubspec.yaml
dependencies:
  material_ui: ^1.3.0

Or via command line:

flutter pub add material_ui

Step 2: Update Imports

Replace all occurrences in every Dart file:

// Before
import 'package:flutter/material.dart';

// After
import 'package:material_ui/material_ui.dart';

If you also use Cupertino widgets:

// Before
import 'package:flutter/cupertino.dart';

// After
import 'package:cupertino_ui/cupertino_ui.dart';

Bulk Find and Replace

In VS Code: Ctrl+Shift+H (Find and Replace)

• Find: package:flutter/material.dart
• Replace: package:material_ui/material_ui.dart
• Check “Use Regular Expression” if needed.
• Click “Replace All”.

In Android Studio/IntelliJ: Ctrl+Shift+R (Replace in Files)

• Same find/replace pattern.

Step 3: Update pubspec.yaml

Remove any direct dependency on flutter_localizations if you were using it only for Material/Cupertino delegates:

# Before
dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter

# After
dependencies:
  flutter:
    sdk: flutter
  material_ui: ^1.3.0

Migrating Localizations

Localizations have been decoupled. The setup is now simpler.

Before

import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter/material.dart';

MaterialApp(
  localizationsDelegates: const <LocalizationsDelegate<dynamic>>[
    GlobalCupertinoLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
  ],
  supportedLocales: [
    const Locale('en', ''),
    const Locale('es', ''),
  ],
);

After

import 'package:material_ui/material_ui.dart';

MaterialApp(
  localizationsDelegates: GlobalMaterialLocalizations.delegates,
  supportedLocales: [
    const Locale('en', ''),
    const Locale('es', ''),
  ],
);

GlobalMaterialLocalizations.delegates now includes the Cupertino and Widgets delegates automatically. One line replaces three.

Handling Legacy Dependencies (Compatibility Bridge)

The biggest challenge with migration is third-party packages that still import package:flutter/material.dart. The MaterialUiCompatibilityBridge solves this.

The Problem

Your app uses package:material_ui, but a dependency like some_package still uses package:flutter/material.dart. This creates a conflict because ThemeData from the old import is different from ThemeData in material_ui.

The Solution

Wrap your app (or affected subtrees) with the compatibility bridge:

import 'package:material_ui/material_ui.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFF6750A4)),
      ),
      builder: (BuildContext context, Widget? child) {
        return MaterialUiCompatibilityBridge(child: child!);
      },
      home: const HomeScreen(),
    );
  }
}

Wrapping Individual Subtrees

If only specific widgets from legacy packages need bridging:

Scaffold(
  appBar: AppBar(title: const Text('Modern Screen')),
  body: MaterialUiCompatibilityBridge(
    child: LegacyPackageWidget(),
  ),
)

When to Remove the Bridge

Once all your dependencies migrate to material_ui, you can remove the MaterialUiCompatibilityBridge wrapper. Check periodically by searching your pubspec.lock for packages still depending on package:flutter/material.dart.

Guidance for Package Authors

If you maintain a Flutter package on pub.dev:

1. Treat this as a major version bump — update your package to material_ui and publish a new major version.
2. Update your imports in all package source files.
3. Update your example app to use the new imports.
4. Add material_ui to your pubspec.yaml dependencies.
5. Test thoroughly — the standalone packages are functionally identical, but verify no regressions.

# Your package's pubspec.yaml
dependencies:
  material_ui: ^1.3.0
  flutter:
    sdk: flutter

Migration Checklist

Step	Command/Action
Upgrade Flutter	flutter upgrade
Run automated fix	dart fix --apply --code=migrate_design_widgets
If pubspec fails	flutter pub add material_ui then re-run fix
Update localizations	Replace 3 delegates with GlobalMaterialLocalizations.delegates
Bridge legacy deps	Add MaterialUiCompatibilityBridge in MaterialApp.builder
Verify imports	grep -r "package:flutter/material.dart" lib/
Run tests	flutter test
Build & verify	flutter build apk --debug

Timeline

Date	Event
August 2026	Flutter 3.47: material_ui 1.0.0 on pub.dev
Now	Opt-in migration available via dart fix
November 2026	Formal deprecation of in-framework Material in Fall stable
Future	Removal of in-framework Material from Flutter SDK

Troubleshooting

”Method ‘X’ is not defined for type ‘ThemeData’”

This usually means you have a mix of old and new imports. Ensure all files in your project use package:material_ui/material_ui.dart.

”Could not find package ‘material_ui’”

Run flutter pub get after adding the dependency.

Legacy package still uses package:flutter/material.dart

Use MaterialUiCompatibilityBridge as shown above. Report the issue to the package maintainer.

Build errors after migration

Clean and rebuild:

flutter clean
flutter pub get
flutter run

Sources:

• Migrate to standalone material_ui and cupertino_ui packages
• What’s new in Flutter 3.47
• Material and Cupertino decoupling are here
• material_ui on pub.dev