flutter · Sten435 · Jun 10, 2025 · Jun 10, 2025 · Jun 10, 2025 · Jun 11, 2025
diff --git a/packages/flutter/lib/src/material/progress_indicator.dart b/packages/flutter/lib/src/material/progress_indicator.dart
@@ -348,6 +348,7 @@ class LinearProgressIndicator extends ProgressIndicator {
       'This feature was deprecated after v3.26.0-0.1.pre.',
     )
     this.year2023,
+    this.controller,
   }) : assert(minHeight == null || minHeight > 0);
 
   /// {@template flutter.material.LinearProgressIndicator.trackColor}
@@ -427,39 +428,81 @@ class LinearProgressIndicator extends ProgressIndicator {
   )
   final bool? year2023;
 
+  /// ## Animation synchronization
+  ///
+  /// When multiple [ProgressIndicator] widgets are animating on screen
+  /// simultaneously (e.g., in a list of loading items), their uncoordinated
+  /// animations can appear visually cluttered. To address this, the animation of
+  /// an indicator can be driven by a custom [AnimationController].
+  ///
+  /// This allows multiple indicators to be synchronized to a single animation
+  /// source. The most convenient way to achieve this for a group of indicators is
+  /// by providing a controller via [ProgressIndicatorTheme]. All
+  /// [ProgressIndicator] widgets within that theme's subtree will then share
+  /// the same animation, resulting in a more coordinated and visually pleasing
+  /// effect.
+  ///
+  /// Alternatively, a specific [AnimationController] can be passed directly to the
+  /// [controller] property of an individual indicator.
+  final AnimationController? controller;
+
+  /// The default duration for [LinearProgressIndicator] animation.
+  static const Duration defaultAnimationDuration = Duration(
+    milliseconds: _kIndeterminateLinearDuration,
+  );
+
   @override
   State<LinearProgressIndicator> createState() => _LinearProgressIndicatorState();
 }
 
 class _LinearProgressIndicatorState extends State<LinearProgressIndicator>
     with SingleTickerProviderStateMixin {
-  late AnimationController _controller;
+  late AnimationController _internalController;
+  AnimationController? _inheritedController;
+
+  AnimationController get _controller =>
+      widget.controller ?? _inheritedController ?? _internalController;
+
+  bool get _usingInternalController => _controller == _internalController;
 
   @override
   void initState() {
     super.initState();
-    _controller = AnimationController(
-      duration: const Duration(milliseconds: _kIndeterminateLinearDuration),
+    _inheritedController =
+        context.getInheritedWidgetOfExactType<ProgressIndicatorTheme>()?.data.controller ??
+        context.findAncestorWidgetOfExactType<Theme>()?.data.progressIndicatorTheme.controller;
+
+    _internalController = AnimationController(
+      duration: LinearProgressIndicator.defaultAnimationDuration,
       vsync: this,
     );
-    if (widget.value == null) {
+
+    if (_usingInternalController && widget.value == null) {
       _controller.repeat();
     }
   }
 
   @override
   void didUpdateWidget(LinearProgressIndicator oldWidget) {
     super.didUpdateWidget(oldWidget);
-    if (widget.value == null && !_controller.isAnimating) {
-      _controller.repeat();
-    } else if (widget.value != null && _controller.isAnimating) {
-      _controller.stop();
+    if (_usingInternalController) {
+      if (widget.value == null && !_controller.isAnimating) {
+        _controller.repeat();
+      } else if (widget.value != null && _controller.isAnimating) {
+        _controller.stop();
+      }
     }
   }
 
+  @override
+  void didChangeDependencies() {
+    super.didChangeDependencies();
+    _inheritedController = ProgressIndicatorTheme.of(context).controller;
+  }
+
   @override
   void dispose() {
-    _controller.dispose();
+    _internalController.dispose();
     super.dispose();
   }
 
@@ -722,6 +765,7 @@ class CircularProgressIndicator extends ProgressIndicator {
     )
     this.year2023,
     this.padding,
+    this.controller,
   }) : _indicatorType = _ActivityIndicatorType.material;
 
   /// Creates an adaptive progress indicator that is a
@@ -753,6 +797,7 @@ class CircularProgressIndicator extends ProgressIndicator {
     )
     this.year2023,
     this.padding,
+    this.controller,
   }) : _indicatorType = _ActivityIndicatorType.adaptive;
 
   final _ActivityIndicatorType _indicatorType;
@@ -844,6 +889,24 @@ class CircularProgressIndicator extends ProgressIndicator {
   /// padding. Otherwise, defaults to zero padding.
   final EdgeInsetsGeometry? padding;
 
+  /// ## Animation synchronization
+  ///
+  /// When multiple [ProgressIndicator] widgets are animating on screen
+  /// simultaneously (e.g., in a list of loading items), their uncoordinated
+  /// animations can appear visually cluttered. To address this, the animation of
+  /// an indicator can be driven by a custom [AnimationController].
+  ///
+  /// This allows multiple indicators to be synchronized to a single animation
+  /// source. The most convenient way to achieve this for a group of indicators is
+  /// by providing a controller via [ProgressIndicatorTheme]. All
+  /// [ProgressIndicator] widgets within that theme's subtree will then share
+  /// the same animation, resulting in a more coordinated and visually pleasing
+  /// effect.
+  ///
+  /// Alternatively, a specific [AnimationController] can be passed directly to the
+  /// [controller] property of an individual indicator.
+  final AnimationController? controller;
+
   /// The indicator stroke is drawn fully inside of the indicator path.
   ///
   /// This is a constant for use with [strokeAlign].
@@ -863,6 +926,11 @@ class CircularProgressIndicator extends ProgressIndicator {
   /// This is a constant for use with [strokeAlign].
   static const double strokeAlignOutside = 1.0;
 
+  /// The default duration for [CircularProgressIndicator] animation.
+  static const Duration defaultAnimationDuration = Duration(
+    milliseconds: _kIndeterminateCircularDuration,
+  );
+
   @override
   State<CircularProgressIndicator> createState() => _CircularProgressIndicatorState();
 }
@@ -883,33 +951,52 @@ class _CircularProgressIndicatorState extends State<CircularProgressIndicator>
     curve: const SawTooth(_rotationCount),
   );
 
-  late AnimationController _controller;
+  late AnimationController _internalController;
+  AnimationController? _inheritedController;
+
+  AnimationController get _controller =>
+      widget.controller ?? _inheritedController ?? _internalController;
+
+  bool get _usingInternalController => _controller == _internalController;
 
   @override
   void initState() {
     super.initState();
-    _controller = AnimationController(
-      duration: const Duration(milliseconds: _kIndeterminateCircularDuration),
+    _inheritedController =
+        context.getInheritedWidgetOfExactType<ProgressIndicatorTheme>()?.data.controller ??
+        context.findAncestorWidgetOfExactType<Theme>()?.data.progressIndicatorTheme.controller;
+
+    _internalController = AnimationController(
+      duration: CircularProgressIndicator.defaultAnimationDuration,
       vsync: this,
     );
-    if (widget.value == null) {
+
+    if (_usingInternalController && widget.value == null) {
       _controller.repeat();
     }
   }
 
   @override
   void didUpdateWidget(CircularProgressIndicator oldWidget) {
     super.didUpdateWidget(oldWidget);
-    if (widget.value == null && !_controller.isAnimating) {
-      _controller.repeat();
-    } else if (widget.value != null && _controller.isAnimating) {
-      _controller.stop();
+    if (_usingInternalController) {
+      if (widget.value == null && !_controller.isAnimating) {
+        _controller.repeat();
+      } else if (widget.value != null && _controller.isAnimating) {
+        _controller.stop();
+      }
     }
   }
 
+  @override
+  void didChangeDependencies() {
+    super.didChangeDependencies();
+    _inheritedController = ProgressIndicatorTheme.of(context).controller;
+  }
+
   @override
   void dispose() {
-    _controller.dispose();
+    _internalController.dispose();
     super.dispose();
   }
 

diff --git a/packages/flutter/lib/src/material/progress_indicator_theme.dart b/packages/flutter/lib/src/material/progress_indicator_theme.dart
@@ -54,6 +54,7 @@ class ProgressIndicatorThemeData with Diagnosticable {
       'This feature was deprecated after v3.27.0-0.2.pre.',
     )
     this.year2023,
+    this.controller,
   });
 
   /// The color of the [ProgressIndicator]'s indicator.
@@ -138,6 +139,24 @@ class ProgressIndicatorThemeData with Diagnosticable {
   )
   final bool? year2023;
 
+  /// ## Animation synchronization
+  ///
+  /// When multiple [ProgressIndicator] widgets are animating on screen
+  /// simultaneously (e.g., in a list of loading items), their uncoordinated
+  /// animations can appear visually cluttered. To address this, the animation of
+  /// an indicator can be driven by a custom [AnimationController].
+  ///
+  /// This allows multiple indicators to be synchronized to a single animation
+  /// source. The most convenient way to achieve this for a group of indicators is
+  /// by providing a controller via [ProgressIndicatorTheme]. All
+  /// [ProgressIndicator] widgets within that theme's subtree will then share
+  /// the same animation, resulting in a more coordinated and visually pleasing
+  /// effect.
+  ///
+  /// Alternatively, a specific [AnimationController] can be passed directly to the
+  /// [controller] property of an individual indicator.
+  final AnimationController? controller;
+
   /// Creates a copy of this object but with the given fields replaced with the
   /// new values.
   ProgressIndicatorThemeData copyWith({
@@ -156,6 +175,7 @@ class ProgressIndicatorThemeData with Diagnosticable {
     double? trackGap,
     EdgeInsetsGeometry? circularTrackPadding,
     bool? year2023,
+    AnimationController? controller,
   }) {
     return ProgressIndicatorThemeData(
       color: color ?? this.color,
@@ -173,6 +193,7 @@ class ProgressIndicatorThemeData with Diagnosticable {
       trackGap: trackGap ?? this.trackGap,
       circularTrackPadding: circularTrackPadding ?? this.circularTrackPadding,
       year2023: year2023 ?? this.year2023,
+      controller: controller ?? this.controller,
     );
   }
 
@@ -207,6 +228,7 @@ class ProgressIndicatorThemeData with Diagnosticable {
         t,
       ),
       year2023: t < 0.5 ? a?.year2023 : b?.year2023,
+      controller: t < 0.5 ? a?.controller : b?.controller,
     );
   }
 
@@ -227,6 +249,7 @@ class ProgressIndicatorThemeData with Diagnosticable {
     trackGap,
     circularTrackPadding,
     year2023,
+    controller,
   );
 
   @override
@@ -252,7 +275,8 @@ class ProgressIndicatorThemeData with Diagnosticable {
         other.constraints == constraints &&
         other.trackGap == trackGap &&
         other.circularTrackPadding == circularTrackPadding &&
-        other.year2023 == year2023;
+        other.year2023 == year2023 &&
+        other.controller == controller;
   }
 
   @override
@@ -285,6 +309,9 @@ class ProgressIndicatorThemeData with Diagnosticable {
       ),
     );
     properties.add(DiagnosticsProperty<bool>('year2023', year2023, defaultValue: null));
+    properties.add(
+      DiagnosticsProperty<AnimationController>('controller', controller, defaultValue: null),
+    );
   }
 }
 

diff --git a/packages/flutter/test/material/progress_indicator_test.dart b/packages/flutter/test/material/progress_indicator_test.dart
@@ -567,6 +567,80 @@ void main() {
     expect(tester.binding.transientCallbackCount, 0);
   });
 
+  testWidgets('LinearProgressIndicator reflects controller value', (WidgetTester tester) async {
+    final AnimationController controller = AnimationController(
+      vsync: tester,
+      duration: const Duration(seconds: 2),
+    );
+
+    Widget buildWidget(AnimationController? controller) {
+      return MaterialApp(
+        home: Material(
+          child: Center(
+            child: AnimatedBuilder(
+              animation: controller!,
+              builder: (BuildContext context, Widget? child) {
+                return LinearProgressIndicator(value: controller.value);
+              },
+            ),
+          ),
+        ),
+      );
+    }
+
+    await tester.pumpWidget(buildWidget(controller));
+    await tester.pump(const Duration(milliseconds: 100)); // build
+
+    expect(find.byType(LinearProgressIndicator), paints..rect());
+
+    controller.value = 0.5;
+    await tester.pump(); // triggers rebuild via AnimatedBuilder
+
+    expect(find.byType(LinearProgressIndicator), paints..rect());
+    controller.dispose();
+  });
+
+  testWidgets('LinearProgressIndicator paints at 50% when controller value is 0.5', (
+    WidgetTester tester,
+  ) async {
+    final AnimationController controller = AnimationController(
+      vsync: tester,
+      duration: const Duration(seconds: 2),
+    );
+
+    Widget buildWidget(AnimationController? controller) {
+      return MaterialApp(
+        home: Material(
+          child: Center(
+            child: SizedBox(
+              width: 200,
+              child: AnimatedBuilder(
+                animation: controller!,
+                builder: (BuildContext context, Widget? child) {
+                  return LinearProgressIndicator(value: controller.value);
+                },
+              ),
+            ),
+          ),
+        ),
+      );
+    }
+
+    await tester.pumpWidget(buildWidget(controller));
+    await tester.pump();
+
+    controller.value = 0.5;
+    await tester.pump();
+
+    expect(
+      find.byType(LinearProgressIndicator),
+      paints
+        ..rect(rect: const Rect.fromLTWH(0.0, 0.0, 200.0, 4.0)) // background
+        ..rect(rect: const Rect.fromLTWH(0.0, 0.0, 100.0, 4.0)), // progress at 50%
+    );
+    controller.dispose();
+  });
+
   testWidgets('CircularProgressIndicator paint colors', (WidgetTester tester) async {
     const Color green = Color(0xFF00FF00);
     const Color blue = Color(0xFF0000FF);