Migrate to standalone material_ui and cupertino_ui packages

To migrate your project from the in-framework design libraries to the standalone packages, you can use the automated dart fix tool or perform the migration manually.

Automated migration with dart fix

The quickest way to migrate is using the migrate_design_widgets fix rule with dart fix:

$ dart fix --apply --code=migrate_design_widgets

This command automatically updates your imports from package:flutter/material.dart and package:flutter/cupertino.dart to the corresponding standalone package imports.

pubspec.yaml dependencies, manually add them by running flutter pub add material_ui or flutter pub add cupertino_ui as needed.

and lint warnings addressed, such as import sorting.

Manual migration

To migrate manually, follow these steps:

1. Add the standalone packages to your pubspec.yaml dependencies:

   $ flutter pub add material_ui
   $ flutter pub add cupertino_ui

2. Update the imports in your Dart files to reference the new packages.

   Code before migration:

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

   Code after migration:

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

Compatibility bridge

During the ecosystem transition, your application might depend on third-party packages that still import the legacy in-framework libraries (package:flutter/material.dart or package:flutter/cupertino.dart).

To allow your application to migrate to the standalone packages immediately without waiting for all dependencies to update, material_ui and cupertino_ui provide compatibility bridge utilities. Wrap your app using MaterialUiCompatibilityBridge inside MaterialApp.builder:

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(),
    );
  }
}

Bridge capabilities and limitations

MaterialUiCompatibilityBridge injects theme and localization data downward into the widget tree. This allows unmigrated child widgets and dependencies that read design state from context (such as Theme.of(context) or MaterialLocalizations.of(context)) to continue functioning properly.

However, the compatibility bridge cannot resolve type mismatches when a dependency exposes, accepts, or returns in-framework SDK types in its public API signatures (such as passing a FloatingActionButtonLocation, ColorScheme, or TextTheme as a parameter or callback return value). Because Dart enforces static typing across distinct package imports, values from package:flutter/material.dart cannot be assigned to parameters expecting types from package:material_ui. Dependencies with API-signature coupling must be migrated to the standalone package before your application can pass modern types to them.

Decoupled localizations

As part of this transition, flutter_localizations is unbundled for design components. Localization delegates and translated strings for Material and Cupertino widgets now reside directly in package:material_ui and package:cupertino_ui.

Code before migration:

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

// ...
MaterialApp(
  localizationsDelegates: const <LocalizationsDelegate<dynamic>>[
    GlobalCupertinoLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
  ],
  // ...
);

Code after migration:

import 'package:material_ui/material_ui.dart';

// ...
MaterialApp(
  localizationsDelegates: GlobalMaterialLocalizations.delegates,
  // ...
);

Setting localizationsDelegates to GlobalMaterialLocalizations.delegates automatically includes the Cupertino and Widgets delegates as well, simplifying localization setup.

Guidance for package authors

If you maintain an open source package or plugin in the Flutter ecosystem, migrating to package:material_ui or package:cupertino_ui introduces a breaking change for consumers who haven't updated their dependencies. While the symbols and class names remain the same, they are technically referenced from an entirely new library. Treat this migration as a major version bump for your package.