Flutter UI Decoupling: A Developer's Handbook for Material & Cupertino

Flutter 3.47, released in August 2026, marks a significant architectural shift that impacts every Flutter developer. Earlier this year, the Flutter team announced plans to separate the Material and Cupertino design libraries from the core SDK into standalone packages on pub.dev. What was once a preview is now the present reality, with material_ui and cupertino_ui reaching version 1.0, the migration tooling complete, and the deprecation clock for old imports officially ticking. This handbook provides a practical guide to understanding, adopting, and working with this new decoupled architecture.

The Architectural Shift: Why It Matters

Before Flutter 3.47, importing package:flutter/material.dart meant pulling in the Material widget library directly bundled within the Flutter SDK. This tightly coupled structure implied that any bug fixes or new features for Material Design components were tied to the quarterly Flutter SDK release cycle. This created several limitations:

• Slow Feature Rollouts: Major design updates, like Material Design 3, experienced delays because they had to wait for an entire SDK release.
• Contribution Barriers: Community contributions to UI components were harder to merge due to the high bar for modifying core SDK code.
• Unnecessary Dependencies: Projects using entirely custom design systems still implicitly depended on Material and Cupertino, even if they didn't use them.
• Interdependent Releases: Material and Cupertino followed the same release cadence, preventing independent versioning and urgent updates for one without affecting the other.

The decoupling initiative resolves these issues. The core Flutter SDK now focuses on rendering, base widgets, and platform services, while material_ui and cupertino_ui are independent, first-party packages on pub.dev. This allows for weekly updates for UI components, reduces unnecessary dependencies, and paves the way for a truly style-neutral Flutter core.

Critically, your existing Flutter code still compiles in version 3.47. The old package:flutter/material.dart and package:flutter/cupertino.dart imports will continue to function for a grace period, with formal deprecation scheduled for November 2026. However, the migration clock has started.

Setting Up and Migrating Your Project

The first step to adopting the new architecture is to add the new UI packages to your project.

Adding the New Packages

Use flutter pub add to include material_ui and cupertino_ui in your pubspec.yaml:

bash flutter pub add material_ui

This command adds material_ui: ^1.0.0 to your pubspec.yaml and runs flutter pub get. The ^1.0.0 constraint allows compatible minor and patch updates while preventing breaking changes from a major version bump. If your project uses Cupertino widgets, add cupertino_ui similarly:

bash flutter pub add cupertino_ui

For efficiency, you can add both packages simultaneously:

bash flutter pub add material_ui cupertino_ui

Automated Migration with dart fix

The Flutter team provides an automated tool to handle most of the migration work:

bash dart fix --apply --code=migrate_design_widgets

This command leverages Dart's built-in code repair tool. The --apply flag automatically applies all suggested fixes, and --code=migrate_design_widgets specifically targets the import changes. It scans for package:flutter/material.dart and package:flutter/cupertino.dart and updates them to package:material_ui/material_ui.dart and package:cupertino_ui/cupertino_ui.dart respectively. The tool also attempts to update your pubspec.yaml, though an early bug might sometimes require manual intervention for the pubspec.yaml step.

Addressing the pubspec.yaml Bug: If dart fix doesn't update your pubspec.yaml correctly, first manually add the packages as shown above, then run dart fix --apply again (without the --code flag this time) to apply any remaining fixes now that the dependencies are resolved.

Verification: After migration, run flutter analyze to ensure no issues related to missing imports or deprecated APIs remain.

What dart fix changes:

dart // BEFORE: Old bundled imports import 'package:flutter/material.dart'; import 'package:flutter/cupertino.dart';

dart // AFTER: New standalone package imports import 'package:material_ui/material_ui.dart'; import 'package:cupertino_ui/cupertino_ui.dart';

The key takeaway is that widget names and API surfaces remain unchanged. Scaffold, ThemeData, and other familiar widgets are identical; only their import paths have changed.

Manual Migration Scenarios

While dart fix is powerful, some cases require manual adjustments:

• Mixed Import Files: If a file imports from package:flutter/material.dart alongside other core Flutter framework libraries (e.g., package:flutter/rendering.dart, package:flutter/services.dart), only the design system imports will change. Core framework imports like rendering.dart remain untouched, as they are not part of the decoupled design systems.
• Conditional Imports: Imports using if (dart.library.html) or similar platform conditions might need both branches of the conditional import to be manually updated.
• Generated Files: Files ending in .g.dart or .freezed.dart should not be manually edited. After migrating your source files, simply regenerate them by running dart run build_runner build --delete-conflicting-outputs. The build runner will pick up the updated imports from your source files.

The MaterialUiCompatibilityBridge

One of the most crucial aspects of this transition is handling dependencies. It's highly probable that some third-party packages you use haven't yet migrated to the new material_ui imports. This can lead to a mix of new and old Material widgets in your application's widget tree. The MaterialUiCompatibilityBridge is designed precisely for this situation.

It acts as a compatibility layer, allowing widgets from both the new standalone material_ui package and the old bundled package:flutter/material.dart to coexist harmoniously without runtime errors.

To use it, wrap your app's main content with MaterialUiCompatibilityBridge within your MaterialApp's builder property:

dart 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!); // <-- Insert bridge here }, home: const HomeScreen(), ); } }

By placing the bridge in the MaterialApp's builder, it wraps the entire widget tree, ensuring that all Material widgets, regardless of their origin, can operate together. This bridge is a temporary solution to smooth the ecosystem's transition, not a permanent fixture. As third-party packages migrate, you should aim to remove it.

Best Practices and Common Mistakes

To ensure a smooth migration, keep these points in mind:

• Migrate Early, Migrate Once: The sooner you update, the easier it will be to address any issues, and you'll benefit from faster UI component updates.
• Use the Compatibility Bridge Temporarily: The MaterialUiCompatibilityBridge is a lifeline during the transition, but aim to remove it once all your dependencies have migrated. Its purpose is compatibility, not permanent coexistence.
• Pin Package Versions in CI: In your CI/CD pipelines, consider pinning specific material_ui and cupertino_ui versions (e.g., material_ui: 1.0.0) to ensure consistent builds during the initial migration period, especially if you anticipate rapid updates.

Avoid these common pitfalls:

• Mixing Old and New Imports: Do not import package:flutter/material.dart and package:material_ui/material_ui.dart in the same file. This will lead to conflicts and potential runtime issues. The migration tool's job is to prevent this.
• Forgetting the Compatibility Bridge: If you encounter runtime errors related to Material widgets from different sources, it's likely you forgot to implement the MaterialUiCompatibilityBridge.
• Running pub get After dart fix Without Adding Packages: Always add material_ui and cupertino_ui to your pubspec.yaml before running dart fix, or use flutter pub add first. Otherwise, dart fix cannot resolve the new imports.

FAQ

Q: Do I need to migrate my project immediately? A: While old imports still work in Flutter 3.47, the deprecation clock has started, with formal deprecation expected in November 2026. Migrating early is a best practice to avoid future breaking changes and benefit from independent UI package updates.

Q: What if a third-party package I use hasn't migrated yet? A: This is precisely what the MaterialUiCompatibilityBridge is for. Implement it in your MaterialApp's builder property to allow your newly migrated code to coexist with unmigrated third-party dependencies.

Q: Are there any performance implications from using the MaterialUiCompatibilityBridge? A: The bridge adds a slight overhead to the widget tree, as it's a compatibility layer. For a temporary solution, this is generally negligible. However, for long-term performance and cleaner architecture, the goal should be to remove the bridge once all your direct and indirect dependencies have fully migrated to the new standalone UI packages.