Flutter Material and Cupertino Migration Guide

Flutter now ships Material and Cupertino as standalone packages on pub.dev. Existing apps can migrate from `package:flutter/material.dart` and `package:flutter/cupertino.dart` with an official automated Dart fix.

TL;DR

Run the official migration fix, then verify package versions, localizations, and third-party dependencies:

dart fix --apply --code=migrate_design_widgets
flutter analyze
flutter test

As of October 3, 2026, the current package releases are `material_ui ^1.5.0` and `cupertino_ui ^1.1.1`.

Prerequisites

Flutter 3.47.6 stable
Dart 3.13.5
Platforms – Android, iOS, web, macOS, Windows, and Linux
Material package – `material_ui ^1.5.0`
Cupertino package – `cupertino_ui ^1.1.1`

Step 1 – Add the Standalone UI Packages

Add only the design libraries your app uses:

flutter pub add material_ui:^1.5.0
flutter pub add cupertino_ui:^1.1.1

The resulting dependency section should look like this:

dependencies:
  flutter:
    sdk: flutter
  material_ui: ^1.5.0
  cupertino_ui: ^1.1.1

If your app only uses Material, you do not need to add `cupertino_ui` directly unless your code imports it.

Step 2 – Run the Automated Migration

Flutter provides a data-driven fix for the import migration:

dart fix --apply --code=migrate_design_widgets

The migration replaces imports such as:

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

With:

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

Run the fix from the project root so it can update the app consistently.

Step 3 – Update Localizations

Apps that use `GlobalMaterialLocalizations` or `GlobalCupertinoLocalizations` should use the versions shipped with the standalone UI packages.

A Material app can use:

import 'package:material_ui/material_ui.dart';

MaterialApp(
  localizationsDelegates: GlobalMaterialLocalizations.delegates,
  home: const HomeScreen(),
);

`GlobalMaterialLocalizations.delegates` includes the Material, Cupertino, and Widgets delegates needed for a typical app.

Step 4 – Bridge Legacy Dependencies

Some packages may still import the old core Material library. Use `MaterialUiCompatibilityBridge` while the dependency ecosystem catches up:

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(
      builder: (BuildContext context, Widget? child) {
        return MaterialUiCompatibilityBridge(child: child!);
      },
      home: const HomeScreen(),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(child: Text('Standalone Material UI')),
    );
  }
}

For Cupertino apps, the equivalent bridge is `CupertinoUiCompatibilityBridge`.

Verify It Works

Run static analysis and tests:

flutter analyze
flutter test

Then launch each platform you ship:

flutter run

Confirm that themes, dialogs, navigation, text fields, localizations, and any package-provided widgets still render correctly.

Troubleshooting

Error – package material_ui not found

Fix – run `flutter pub get` and confirm `material_ui` is present in `pubspec.yaml`.

Error – legacy package widgets cannot find ThemeData

Fix – wrap the affected subtree or app with `MaterialUiCompatibilityBridge`.

Error – localization classes are missing

Fix – remove old `flutter_localizations` imports for Material or Cupertino delegates and import the standalone UI package.

Error – automated migration does not update pubspec.yaml

Fix – add the package manually with `flutter pub add`, then run the Dart fix again.

Error – package consumers break after your library migrates

Fix – treat the migration as a major release for reusable packages because public types and imports can change for downstream users.

Variations / Alternatives

Keep the core SDK imports temporarily if you are not ready to migrate. Flutter 3.47 still includes the in-framework libraries during the transition.

Migrate app code first and bridge legacy package subtrees. This reduces the number of dependency upgrades required in one change.

For design-system packages, migrate in a dedicated major version so consumers can opt in deliberately.

Performance & Pitfalls

Moving to standalone UI packages is primarily an architecture and release-cadence change, not a guaranteed runtime performance improvement.

Material and Cupertino can now release independently from the quarterly Flutter SDK cycle, so review package changelogs before upgrades.

Keep `pubspec.lock` committed for applications so weekly UI package updates do not surprise production builds.

Test accessibility semantics after migration, especially around dialogs, form controls, navigation, and custom wrappers.

References

Tested Versions

Version references verified against Flutter 3.47.6 stable, Dart 3.13.5, material_ui 1.5.0, and cupertino_ui 1.1.1.