As described in thebreaking change policy, on occasion we publish guides for migrating code across a breaking change.

To be notified about future breaking changes, join the groupsFlutter announce andDart announce.

When facing Dart errors after upgrading Flutter, consider using thedart fix command to automatically migrate your code. Not every breaking change is supported in this way, but many are.

To avoid being broken by future versions of Flutter, consider submitting your tests to the framework'stest registry.

The following guides are available. They're sorted by release and listed in alphabetical order:

• Migrating Flutter Android app to Android Gradle Plugin 9.0.0
• DeprecateonReorder callback
• DeprecatedcacheExtent andcacheExtentStyle
• Page transition builders reorganization

• Merged threads on Linux
• FontWeight also controls the weight attribute of variable fonts
• DeprecatecontainsSemantics in favor ofisSemantics
• DeprecatefindChildIndexCallback in favor offindItemIndexCallback inListView andSliverList separated constructors
• Material 3 tokens update

• CupertinoDynamicColor wide gamut support
• DeprecateOverlayPortal.targetsRootOverlay
• DeprecateSemanticsProperties.focusable andSemanticsConfiguration.isFocusable
• SnackBar with action no longer auto-dismisses
• The default page transition on Android is nowPredictiveBackPageTransitionBuilder
• UISceneDelegate adoption

• Component theme normalization updates
• DeprecateDropdownButtonFormFieldvalue parameter in favor ofinitialValue
• Deprecate app bar color
• Redesigned theRadio widget
• Removed semantics elevation and thickness
• TheForm widget no longer supports being a sliver
• Flutter now sets defaultabiFilters in Android builds
• Merged threads on macOS and Windows
• TheVisibility widget is no longer focusable by default whenmaintainState is enabled
• $FLUTTER_ROOT/version replaced by$FLUTTER_ROOT/bin/cache/flutter.version.json

• DeprecateSystemContextMenuController.show
• DeprecateExpansionTileController in favor ofExpansibleController
• DeprecateRouteTransitionRecord.markForRemove in favor ofRouteTransitionRecord.markForComplete
• DeprecateThemeData.indicatorColor in favor ofTabBarThemeData.indicatorColor
• Material Theme System Updates
• .flutter-plugins-dependencies replaces.flutter-plugins
• Localized messages are generated into source, not a synthetic package
• Changing the defaultgoldenFileComparator forintegration_tests
• DeprecateInputDecoration.maintainHintHeight in favor ofInputDecoration.maintainHintSize
• Underdamped spring formula changed

• Removal of v1 Android embedding Java APIs
• DeprecateWebGoldenComparator
• DeprecateThemeData.dialogBackgroundColor in favor ofDialogThemeData.backgroundColor
• ImageFilter.blur default tile mode automatic selection
• Updated Material 3Slider
• Updated Material 3 progress indicators

• Color wide gamut support
• Component theme normalization
• Deep links flag change
• Material 3 Tokens Update in Flutter
• Remove invalid parameters forInputDecoration.collapsed
• Set default for SystemUiMode to Edge-to-Edge

• Navigator's page APIs breaking change
• Generic types inPopScope
• DeprecateButtonBar in favor ofOverflowBar
• New APIs for Android plugins that render to aSurface

• Deprecated API removed after v3.19
• RenameMaterialState toWidgetState
• Introduce newColorScheme roles
• Dropping support for Android KitKat
• NullablePageView.controller
• RenameMemoryAllocations toFlutterMemoryAllocations

• Deprecated API removed after v3.16
• Migrate RawKeyEvent/RawKeyboard system to KeyEvent/HardwareKeyboard system
• Deprecate imperative apply of Flutter's Gradle plugins
• Default multitouch scrolling
• Accessibility traversal order of tooltip changed
• Stop generatingAssetManifest.json

• Migrating to Material 3
• Migrate ShortcutActivator and ShortcutManager to KeyEvent system
• TheThemeData.useMaterial3 property is now set to true by default
• Deprecated API removed after v3.13
• Customize tabs alignment using the newTabBar.tabAlignment property
• DeprecatetextScaleFactor in favor ofTextScaler
• Android 14 nonlinear font scaling enabled
• DeprecatedescribeEnum and updateEnumProperty to be type strict
• Deprecated just-in-time navigation pop APIs for Android Predictive Back
• DeprecatedPaint.enableDithering
• Updated default text styles for menus
• Windows: External windows should notify Flutter engine of lifecycle changes
• Windows build path changed to add the target architecture

• Added missingdispose() for some disposable objects in Flutter
• Deprecated API removed after v3.10
• Added AppLifecycleState.hidden enum value
• Moved ReorderableListView's localized strings from material to widgets localizations
• RemovedignoringSemantics properties
• DeprecatedRouteInformation.location and its related APIs
• Updated EditableText scroll into view behavior
• Migrate a Windows project to ensure the window is shown
• UpdatedCheckbox.fillColor behavior

• Dart 3 changes in Flutter v3.10 and later
• Deprecated API removed after v3.7
• Insert content text input client
• Deprecated the window singleton
• Resolve the Android Java Gradle error
• Require one data variant forClipboardData constructor
• "Zone mismatch" message

• Deprecated API removed after v3.3
• Replaced parameters for customizing context menus with a generic widget builder
• iOS FlutterViewController splashScreenView made nullable
• Migrateof to non-nullable return values, and addmaybeOf
• Removed RouteSettings.copyWith
• ThemeData's toggleableActiveColor property has been deprecated
• Migrate a Windows project to support dark title bars

• Adding ImageProvider.loadBuffer
• Default PrimaryScrollController on Desktop
• Trackpad gestures can trigger GestureRecognizer
• Migrate a Windows project to set version information

• Deprecated API removed after v2.10
• Migrate useDeleteButtonTooltip to deleteButtonTooltipMessage of Chips
• Page transitions replaced by ZoomPageTransitionsBuilder

• Deprecated API removed after v2.5
• Raw images on Web uses correct origin and colors
• Required Kotlin version
• Scribble Text Input Client

• Default drag scrolling devices
• Deprecated API removed after v2.2
• Change the enterText method to move the caret to the end of the input text
• GestureRecognizer cleanup
• Introducing package:flutter_lints
• Replace AnimationSheetBuilder.display with collate
• ThemeData's accent properties have been deprecated
• Transition of platform channel test interfaces to flutter_test package
• Using HTML slots to render platform views in the web
• Migrate a Windows project to the idiomatic run loop

The following breaking change was reverted in release 2.2:

Network Policy on iOS and Android

Introduced in version: 2.0.0
Reverted in version: 2.2.0

• Default Scrollbars on Desktop

• Added BuildContext parameter to TextEditingController.buildTextSpan
• Android ActivityControlSurface attachToActivity signature change
• Android FlutterMain.setIsRunningInRobolectricTest testing API removed
• Clip behavior
• Deprecated API removed after v1.22
• Dry layout support for RenderBox
• Eliminating nullOk Parameters
• Material Chip button semantics
• SnackBars managed by the ScaffoldMessenger
• TextSelectionTheme migration
• Transition of platform channel test interfaces to flutter_test package
• Use maxLengthEnforcement instead of maxLengthEnforced

• Android v1 embedding app and plugin creation deprecation
• Cupertino icons 1.0.0
• The new Form, FormField auto-validation API

• Actions API revision
• Adding TextInputClient.currentAutofillScope property
• New Buttons and Button Themes
• Dialogs' Default BorderRadius
• More Strict Assertions in the Navigator and the Hero Controller Scope
• The Route Transition record and Transition delegate updates
• The RenderEditable needs to be laid out before hit testing
• Reversing the dependency between the scheduler and services layer
• Semantics Order of the Overlay Entries in Modal Routes
• showAutocorrectionPromptRect method added to TextInputClient
• TestWidgetsFlutterBinding.clock
• TextField requires MaterialLocalizations

• Adding 'linux' and 'windows' to TargetPlatform enum
• Annotations return local position relative to object
• Container color optimization
• CupertinoTabBar requires Localizations parent
• Generic type of ParentDataWidget changed to ParentData
• ImageCache and ImageProvider changes
• ImageCache large images
• MouseTracker moved to rendering
• MouseTracker no longer attaches annotations
• Nullable CupertinoTheme.brightness
• Rebuild optimization for OverlayEntries and Routes
• Scrollable AlertDialog
• TestTextInput state reset
• TextInputClient currentTextEditingValue
• The forgetChild() method must call super
• The Route and Navigator refactoring
• FloatingActionButton and ThemeData's accent properties