diff --git a/packages/cupertino_ui/README.md b/packages/cupertino_ui/README.md index b63de459873..6480d867787 100644 --- a/packages/cupertino_ui/README.md +++ b/packages/cupertino_ui/README.md @@ -1,24 +1,138 @@ -# cupertino\_ui +# cupertino_ui -**Coming soon \- the official Cupertino widget library for Flutter as its own standalone package\!** +The official Flutter Cupertino library, implementing Apple's [Human Interface +Guidelines](https://developer.apple.com/design/human-interface-guidelines/) for +Flutter applications. -`cupertino_ui` will contain the standard collection of high-fidelity visual components that implement the latest iOS design language (buttons, navigation bars, pickers, etc.). +`cupertino_ui` provides a complete, high-fidelity suite of visual components, +motion, typography, color system, and theming tools to build authentic +iOS- and macOS-style user interfaces on all screen sizes. -**Note:** This package will contain the cupertino library previously part of the Flutter framework itself (`package:flutter/cupertino.dart`). It is being decoupled to allow for faster iteration and a more modular ecosystem. +See also the +[`material_ui`](https://github.com/flutter/packages/tree/main/packages/material_ui) +package, which is Flutter's official Material Design library. -## What's (going to be) inside? +## New to the package? -This package will provide the Cupertino widgets you know and love, including but not limited to: +Install the package with the following command: -* **Structure:** `CupertinoPageScaffold`, `CupertinoNavigationBar` -* **Inputs:** `CupertinoButton`, `CupertinoTextField`, `CupertinoSwitch` -* **Dialogs:** `CupertinoAlertDialog`, `CupertinoActionSheet` +```dart +flutter add cupertino_ui +``` -Once landed and published, look forward to updates from [iOS26](https://github.com/flutter/flutter/issues/170310)\! 🚀 +See Flutter's main [getting started +guide](https://flutter.dev/getting-started/) for information about using Flutter +and `cupertino_ui`. -## Feedback & roadmap +## Migrating existing code to this package -We are currently migrating the Cupertino library out of the core framework. +The standalone `cupertino_ui` package was previously built directly into the +core Flutter framework as `package:flutter/cupertino.dart`. It has been +decoupled from the [flutter/flutter](https://github.com/flutter/flutter) +repository into its new home here in `flutter/packages`. -* **Follow the progress:** [Decoupling Github Project](https://github.com/orgs/flutter/projects/220) -* **Report bugs:** [Cupertino issues in Flutter](https://github.com/flutter/flutter/issues?q=is%3Aopen%20is%3Aissue%20label%3A%22f%3A%20cupertino%22) +Follow the steps below to migrate: + +### Step 1: Migrate imports + +We've included a data driven Dart fix to help users migrate. Simply run the +following command: + +```sh +dart fix --apply --code=migrate_design_widgets +``` + +This performs the equivalent of adding `cupertino_ui` to your project and +changing imports of `package:flutter/cupertino.dart` to +`package:cupertino_ui/cupertino_ui.dart`. + +### Step 2: Migrate localizations (if needed) + +Don't use the `GlobalMaterialLocalizations` or `GlobalCupertinoLocalizations` +classes from flutter/flutter's `flutter_localizations` package. Instead, use the +new versions of these classes from `material_ui` and `cupertino_ui`, +respectively. + +### Step 3: Bridge legacy dependencies (if needed) + +If your app uses third-party packages or subtrees that still import and rely on +`package:flutter/cupertino.dart`, use `CupertinoUiCompatibilityBridge` to bridge +`CupertinoThemeData` and `CupertinoLocalizations` so legacy widgets resolve +correctly within modern widget trees. + +Wrap your app using `CupertinoApp.builder`: + +```dart +import 'package:cupertino_ui/cupertino_ui.dart'; + +void main() { + runApp(const MyApp()); +} + +class MyApp extends StatelessWidget { + const MyApp({super.key}); + + @override + Widget build(BuildContext context) { + return CupertinoApp( + builder: (BuildContext context, Widget? child) { + return CupertinoUiCompatibilityBridge(child: child!); + }, + home: const HomeScreen(), + ); + } +} +``` + +You can also wrap individual subtrees that contain legacy package widgets: + +```dart +CupertinoPageScaffold( + navigationBar: const CupertinoNavigationBar( + middle: Text('Modern Screen'), + ), + child: CupertinoUiCompatibilityBridge( + child: LegacyPackageWidget(), + ), +) +``` + +--- + +## Features + +The `cupertino_ui` package contains everything you need to create a +fully-featured iOS app, such as: + +* **App Structure & Navigation**: `CupertinoApp`, `CupertinoPageScaffold`, +`CupertinoTabScaffold`, `CupertinoTabView`, `CupertinoNavigationBar`, +`CupertinoSliverNavigationBar`, `CupertinoTabBar`, `CupertinoPageRoute` +* **Buttons & Controls**: `CupertinoButton`, `CupertinoSegmentedControl`, +`CupertinoSlidingSegmentedControl`, `CupertinoContextMenu`, +`CupertinoContextMenuAction`, `CupertinoScrollbar` +* **Inputs & Selection**: `CupertinoTextField`, `CupertinoTextFormFieldRow`, +`CupertinoFormSection`, `CupertinoFormRow`, `CupertinoSwitch`, +`CupertinoSlider`, `CupertinoCheckbox`, `CupertinoRadio`, +`CupertinoSearchTextField` +* **Pickers & Dialogs**: `CupertinoPicker`, `CupertinoDatePicker`, +`CupertinoTimerPicker`, `CupertinoAlertDialog`, `CupertinoActionSheet`, +`CupertinoActionSheetAction`, `CupertinoPopupSurface` +* **Display & Feedback**: `CupertinoListSection`, `CupertinoListTile`, +`CupertinoActivityIndicator`, `CupertinoIcons`, `CupertinoFocusHalo` +* **Theming & Typography**: `CupertinoTheme`, `CupertinoThemeData`, +`CupertinoTextThemeData`, `CupertinoColors`, `CupertinoDynamicColor` +* **Internationalization**: `CupertinoLocalizations` and +`GlobalCupertinoLocalizations` for multi-locale support + +## Changelog + +See the +[Changelog](https://github.com/flutter/packages/blob/main/packages/cupertino_ui/CHANGELOG.md) +for a list of new features and breaking changes. + +## Documentation & Resources + +* [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/) +* [Flutter Cupertino Widget Catalog](https://docs.flutter.dev/ui/widgets/cupertino) +* [API Reference](https://pub.dev/documentation/cupertino_ui/latest/) +* [Issue Tracker](https://github.com/flutter/flutter/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22p%3A%20cupertino_ui%22) diff --git a/packages/cupertino_ui/pending_changelogs/change_2026_08_10_readme.yaml b/packages/cupertino_ui/pending_changelogs/change_2026_08_10_readme.yaml new file mode 100644 index 00000000000..bcf3aba0e92 --- /dev/null +++ b/packages/cupertino_ui/pending_changelogs/change_2026_08_10_readme.yaml @@ -0,0 +1,3 @@ +changelog: | + - README updated for the full release of cupertino_ui. +version: patch diff --git a/packages/material_ui/README.md b/packages/material_ui/README.md index c83917ec2ba..2d558ae72c8 100644 --- a/packages/material_ui/README.md +++ b/packages/material_ui/README.md @@ -1,25 +1,135 @@ -# material\_ui +# material_ui -**Coming soon \- the official Material Design widget library for Flutter as its own standalone package\!** +The official Flutter Material Design library, implementing Google's [Material +Design](https://m3.material.io/) design system for Flutter applications. -`material_ui` will contain the standard collection of visual components (Buttons, Cards, AppBars, etc.) that implement Google's latest Material Design specification. +`material_ui` provides a complete, modern suite of visual components, motion, +typography, color system, and theming tools to build beautiful and accessible +user interfaces on all screen sizes. -**Note:** This package will contain the material library previously part of the Flutter framework itself (`package:flutter/material.dart`). It is being decoupled to allow for faster iteration and a more modular ecosystem. +See also the +[`cupertino_ui`](https://github.com/flutter/packages/tree/main/packages/cupertino_ui) +package, which is Flutter's official iOS- and macOS-style design library. -## What's (going to be) inside? +## New to the package? -This package will provide the Material widgets you know and love, including but not limited to: +Install the package with the following command: -* **Structure:** `Scaffold`, `AppBar`, `Drawer` -* **Inputs:** `FloatingActionButton`, `TextField`, `Slider` -* **Display:** `Card`, `Chip`, `ListTile` -* **Theming:** `ThemeData`, `ColorScheme` +```dart +flutter add material_ui +``` -Once landed and published, look forward to updates from [Material 3 Expressive](https://github.com/flutter/flutter/issues/168813)\! 🚀 +See Flutter's main [getting started +guide](https://flutter.dev/getting-started/) for information about using Flutter +and `material_ui`. -## Feedback & roadmap +## Migrating existing code to this package -We are currently migrating the Material library out of the core framework. +The standalone `material_ui` package was previously built directly into the core +Flutter framework as `package:flutter/material.dart`. It has been decoupled from +the [flutter/flutter](https://github.com/flutter/flutter) repository into its +new home here in `flutter/packages`. -* **Follow the progress:** [Decoupling Github Project](https://github.com/orgs/flutter/projects/220) -* **Report bugs:** [Material issues in Flutter](https://github.com/flutter/flutter/issues?q=is%3Aopen%20is%3Aissue%20label%3A%22f%3A%20material%20design%22) +Follow the steps below to migrate: + +### Step 1: Migrate imports + +We've included a data driven Dart fix to help users migrate. Simply run the +following command: + +```sh +dart fix --apply --code=migrate_design_widgets +``` + +This performs the equivalent of adding `material_ui` to your project and +changing imports of `package:flutter/material.dart` to +`package:material_ui/material_ui.dart`. + +### Step 2: Migrate localizations (if needed) + +If you are not currently using the `GlobalMaterialLocalizations` or +`GlobalCupertinoLocalizations` classes from flutter/flutter's +`flutter_localizations` package, then you are already good to go. For those that +do need to migrate off of these classes, simply use the new versions of these +classes from `material_ui` and `cupertino_ui`, respectively. + +A typical app can use the following localization delegate from `material_ui` to +cover all of the localization strings in Flutter, Material, and Cupertino: + +```dart + localizationDelegates: GlobalMaterialLocalizations.delegates, +``` + +### Step 3: Bridge legacy dependencies (if needed) + +If your app uses third-party packages or subtrees that still import and rely on +`package:flutter/material.dart`, use `MaterialUiCompatibilityBridge` to bridge +`ThemeData` and `MaterialLocalizations` so legacy widgets resolve correctly +within modern widget trees. + +Wrap your app using `MaterialApp.builder`: + +```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( + builder: (BuildContext context, Widget? child) { + return MaterialUiCompatibilityBridge(child: child!); + }, + home: const HomeScreen(), + ); + } +} +``` + +You can also wrap individual subtrees that contain legacy package widgets: + +```dart +Scaffold( + appBar: AppBar(title: const Text('Modern Screen')), + body: MaterialUiCompatibilityBridge( + child: LegacyPackageWidget(), + ), +) +``` + +--- + +## Features + +The `material_ui` packcage contains everything you need to create a +fully-featured Material app, such as: + +* **App Structure & Navigation**: `MaterialApp`, `Scaffold`, `AppBar`, +`NavigationBar`, `BottomSheet`, `TabBar`, `SearchAnchor`, `SearchBar`, `Dialog` +* **Buttons & Interaction**: `ElevatedButton`, `TextButton`, `IconButton`, +`FloatingActionButton`, `SegmentedButton`, `InkWell`, `MenuBar` +* **Inputs & Selection**: `TextField`, `Checkbox`, `Radio`, `Switch`, `Slider`, +`DropdownMenu`, `DatePicker`, `TimePicker` +* **Display & Feedback**: `Card`, `Chip`, `ListTile`, `Badge`, `Divider`, +`ProgressIndicator`, `SnackBar`, `Tooltip`, `CarouselView`, `VerticalDivider` +* **Theming & Color**: `ThemeData`, `ColorScheme`, `TextTheme`, dynamic color +generation, Material 3 design tokens, typography, and motion easing curves +* **Internationalization**: `MaterialLocalizations` and +`GlobalMaterialLocalizations` for multi-locale support + +## Changelog +See the +[Changelog](https://github.com/flutter/packages/blob/main/packages/material_ui/CHANGELOG.md) +for a list of new features and breaking changes. + +## Documentation & Resources + +* [Material Design 3 Specification](https://m3.material.io/) +* [Flutter Material Widget Catalog](https://docs.flutter.dev/ui/widgets/material) +* [API Reference](https://pub.dev/documentation/material_ui/latest/) +* [Issue Tracker](https://github.com/flutter/flutter/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22p%3A%20material_ui%22) diff --git a/packages/material_ui/pending_changelogs/change_2026_08_10_readme.yaml b/packages/material_ui/pending_changelogs/change_2026_08_10_readme.yaml new file mode 100644 index 00000000000..187961310f7 --- /dev/null +++ b/packages/material_ui/pending_changelogs/change_2026_08_10_readme.yaml @@ -0,0 +1,3 @@ +changelog: | + - README updated for the full release of material_ui. +version: patch