|
| 1 | +--- |
| 2 | +title: Migrate to standalone material_ui and cupertino_ui packages |
| 3 | +description: >- |
| 4 | + The Material and Cupertino design libraries are now available as |
| 5 | + standalone packages, decoupling design systems from the Flutter SDK. |
| 6 | +--- |
| 7 | + |
| 8 | +{% render "docs/breaking-changes.md" %} |
| 9 | + |
| 10 | +## Summary |
| 11 | + |
| 12 | +The Material and Cupertino design libraries are now available as |
| 13 | +standalone packages: [`package:material_ui`][] and [`package:cupertino_ui`][]. |
| 14 | +In Flutter 3.47, developers can opt in to these packages ahead of |
| 15 | +the formal deprecation of the in-framework design libraries. |
| 16 | + |
| 17 | +## Background |
| 18 | + |
| 19 | +Historically, Flutter's Material (`package:flutter/material.dart`) |
| 20 | +and Cupertino (`package:flutter/cupertino.dart`) widget libraries |
| 21 | +were bundled directly inside the core Flutter SDK. |
| 22 | +While this made it easy to get started with pixel-perfect widgets, |
| 23 | +bundling design systems inside the core framework presented several challenges: |
| 24 | + |
| 25 | +* Widget updates, bug fixes, and new components were tied to |
| 26 | + quarterly Flutter SDK releases. |
| 27 | +* Contributions and iteration on design libraries moved slower |
| 28 | + than standalone Dart packages. |
| 29 | +* Applications couldn't update design libraries independently of |
| 30 | + the engine and framework. |
| 31 | + |
| 32 | +To resolve these challenges, the design systems are now decoupled |
| 33 | +from the core framework. |
| 34 | +Starting in Flutter 3.47, version 1.0 of the standalone |
| 35 | +`material_ui` and `cupertino_ui` packages is published on `pub.dev`. |
| 36 | + |
| 37 | +Decoupling the design systems provides several benefits: |
| 38 | + |
| 39 | +* **Independent release cycles**: |
| 40 | + The packages can ship bug fixes, improvements, and new components |
| 41 | + on their own release schedules (planned for weekly releases), |
| 42 | + without requiring a full Flutter SDK upgrade. |
| 43 | +* **Faster contributions**: |
| 44 | + Community members can contribute directly to the libraries in the |
| 45 | + [`flutter/packages`][] repository. |
| 46 | +* **Style-neutral core**: |
| 47 | + Decoupling lays the groundwork for a style-neutral Flutter core widget |
| 48 | + catalog, making it easier to build and maintain custom design systems. |
| 49 | + |
| 50 | +Contributions to `package:flutter/material.dart` and |
| 51 | +`package:flutter/cupertino.dart` inside the core SDK were frozen |
| 52 | +starting in Flutter 3.44. |
| 53 | +The initial 1.0.0 versions of `package:material_ui` and `package:cupertino_ui` |
| 54 | +match the frozen framework code to provide a seamless transition. |
| 55 | +Future releases of the packages will use semantic versioning for major, minor, |
| 56 | +and patch updates. |
| 57 | +The in-framework design libraries are scheduled for formal deprecation |
| 58 | +in an upcoming stable release. |
| 59 | + |
| 60 | +## Migration guide |
| 61 | + |
| 62 | +To migrate your project from the in-framework design libraries to the |
| 63 | +standalone packages, you can use the automated `dart fix` tool |
| 64 | +or perform the migration manually. |
| 65 | + |
| 66 | +### Automated migration with dart fix |
| 67 | + |
| 68 | +The quickest way to migrate is using the `migrate_design_widgets` fix rule |
| 69 | +with `dart fix`: |
| 70 | + |
| 71 | +```console |
| 72 | +$ dart fix --apply --code=migrate_design_widgets |
| 73 | +``` |
| 74 | + |
| 75 | +This command automatically updates your imports from |
| 76 | +`package:flutter/material.dart` and `package:flutter/cupertino.dart` |
| 77 | +to the corresponding standalone package imports. |
| 78 | + |
| 79 | +:::note |
| 80 | +If `dart fix` doesn't automatically add the new packages to your |
| 81 | +`pubspec.yaml` dependencies, manually add them by running |
| 82 | +`flutter pub add material_ui` or `flutter pub add cupertino_ui` as needed. |
| 83 | +::: |
| 84 | + |
| 85 | +Run `dart fix` once more to ensure all other automated migrations are applied, |
| 86 | +and lint warnings addressed, such as import sorting. |
| 87 | + |
| 88 | +### Manual migration |
| 89 | + |
| 90 | +To migrate manually, follow these steps: |
| 91 | + |
| 92 | +1. Add the standalone packages to your `pubspec.yaml` dependencies: |
| 93 | + |
| 94 | + ```console |
| 95 | + $ flutter pub add material_ui |
| 96 | + $ flutter pub add cupertino_ui |
| 97 | + ``` |
| 98 | + |
| 99 | +1. Update the imports in your Dart files to reference the new packages. |
| 100 | + |
| 101 | + Code before migration: |
| 102 | + |
| 103 | + ```dart |
| 104 | + import 'package:flutter/cupertino.dart'; |
| 105 | + import 'package:flutter/material.dart'; |
| 106 | + ``` |
| 107 | + |
| 108 | + Code after migration: |
| 109 | + |
| 110 | + ```dart |
| 111 | + import 'package:cupertino_ui/cupertino_ui.dart'; |
| 112 | + import 'package:material_ui/material_ui.dart'; |
| 113 | + ``` |
| 114 | + |
| 115 | +### Compatibility bridge |
| 116 | + |
| 117 | +During the ecosystem transition, your application might depend on |
| 118 | +third-party packages that still import the legacy in-framework libraries |
| 119 | +(`package:flutter/material.dart` or `package:flutter/cupertino.dart`). |
| 120 | + |
| 121 | +To allow your application to migrate to the standalone packages immediately |
| 122 | +without waiting for all dependencies to update, `material_ui` and |
| 123 | +`cupertino_ui` provide compatibility bridge utilities. |
| 124 | +Wrap your app using `MaterialUiCompatibilityBridge` inside |
| 125 | +`MaterialApp.builder`: |
| 126 | + |
| 127 | +```dart |
| 128 | +import 'package:material_ui/material_ui.dart'; |
| 129 | + |
| 130 | +void main() { |
| 131 | + runApp(const MyApp()); |
| 132 | +} |
| 133 | + |
| 134 | +class MyApp extends StatelessWidget { |
| 135 | + const MyApp({super.key}); |
| 136 | + |
| 137 | + @override |
| 138 | + Widget build(BuildContext context) { |
| 139 | + return MaterialApp( |
| 140 | + theme: ThemeData( |
| 141 | + colorScheme: ColorScheme.fromSeed( |
| 142 | + seedColor: const Color(0xFF6750A4), |
| 143 | + ), |
| 144 | + ), |
| 145 | + builder: (BuildContext context, Widget? child) { |
| 146 | + return MaterialUiCompatibilityBridge(child: child!); |
| 147 | + }, |
| 148 | + home: const HomeScreen(), |
| 149 | + ); |
| 150 | + } |
| 151 | +} |
| 152 | +``` |
| 153 | + |
| 154 | +#### Bridge capabilities and limitations |
| 155 | + |
| 156 | +`MaterialUiCompatibilityBridge` injects theme and localization data |
| 157 | +downward into the widget tree. |
| 158 | +This allows unmigrated child widgets and dependencies that read design state |
| 159 | +from context |
| 160 | +(such as `Theme.of(context)` or `MaterialLocalizations.of(context)`) |
| 161 | +to continue functioning properly. |
| 162 | + |
| 163 | +However, the compatibility bridge cannot resolve type mismatches |
| 164 | +when a dependency exposes, accepts, or returns in-framework SDK types |
| 165 | +in its public API signatures (such as passing a `FloatingActionButtonLocation`, |
| 166 | +`ColorScheme`, or `TextTheme` as a parameter or callback return value). |
| 167 | +Because Dart enforces static typing across distinct package imports, |
| 168 | +values from `package:flutter/material.dart` cannot be assigned to parameters |
| 169 | +expecting types from `package:material_ui`. |
| 170 | +Dependencies with API-signature coupling must be migrated to the standalone |
| 171 | +package before your application can pass modern types to them. |
| 172 | + |
| 173 | +### Decoupled localizations |
| 174 | + |
| 175 | +As part of this transition, `flutter_localizations` is unbundled |
| 176 | +for design components. |
| 177 | +Localization delegates and translated strings for Material and Cupertino |
| 178 | +widgets now reside directly in `package:material_ui` and |
| 179 | +`package:cupertino_ui`. |
| 180 | + |
| 181 | +Code before migration: |
| 182 | + |
| 183 | +```dart |
| 184 | +import 'package:flutter/material.dart'; |
| 185 | +import 'package:flutter_localizations/flutter_localizations.dart'; |
| 186 | +
|
| 187 | +// ... |
| 188 | +MaterialApp( |
| 189 | + localizationsDelegates: const <LocalizationsDelegate<dynamic>>[ |
| 190 | + GlobalCupertinoLocalizations.delegate, |
| 191 | + GlobalMaterialLocalizations.delegate, |
| 192 | + GlobalWidgetsLocalizations.delegate, |
| 193 | + ], |
| 194 | + // ... |
| 195 | +); |
| 196 | +``` |
| 197 | + |
| 198 | +Code after migration: |
| 199 | + |
| 200 | +```dart |
| 201 | +import 'package:material_ui/material_ui.dart'; |
| 202 | +
|
| 203 | +// ... |
| 204 | +MaterialApp( |
| 205 | + localizationsDelegates: GlobalMaterialLocalizations.delegates, |
| 206 | + // ... |
| 207 | +); |
| 208 | +``` |
| 209 | + |
| 210 | +Setting `localizationsDelegates` to `GlobalMaterialLocalizations.delegates` |
| 211 | +automatically includes the Cupertino and Widgets delegates as well, |
| 212 | +simplifying localization setup. |
| 213 | + |
| 214 | +### Guidance for package authors |
| 215 | + |
| 216 | +If you maintain an open source package or plugin in the Flutter ecosystem, |
| 217 | +migrating to `package:material_ui` or `package:cupertino_ui` introduces |
| 218 | +a breaking change for consumers who haven't updated their dependencies. |
| 219 | +While the symbols and class names remain the same, |
| 220 | +they are technically referenced from an entirely new library. |
| 221 | +Treat this migration as a major version bump for your package. |
| 222 | + |
| 223 | +## References |
| 224 | + |
| 225 | +Package documentation: |
| 226 | + |
| 227 | +* [`package:material_ui`][] |
| 228 | +* [`package:cupertino_ui`][] |
| 229 | + |
| 230 | +Relevant issues: |
| 231 | + |
| 232 | +* [Issue 191448][] |
| 233 | + |
| 234 | +Relevant blog posts and announcements: |
| 235 | + |
| 236 | +* [What's new in Flutter 3.47][] |
| 237 | +* [Flutter's Material and Cupertino code freeze][] |
| 238 | + |
| 239 | +[`flutter/packages`]: {{site.repo.packages}} |
| 240 | +[Issue 191448]: {{site.repo.flutter}}/issues/191448 |
| 241 | +[`package:cupertino_ui`]: {{site.pub-pkg}}/cupertino_ui |
| 242 | +[`package:material_ui`]: {{site.pub-pkg}}/material_ui |
| 243 | +[Flutter's Material and Cupertino code freeze]: {{site.main-url}}/blog/flutters-material-and-cupertino-code-freeze |
| 244 | +[What's new in Flutter 3.47]: {{site.main-url}}/blog/whats-new-in-flutter-3-47 |
0 commit comments