Image GIF pausing #176492

justinmc · 2025-10-03T22:02:42Z

Flutter needs a strong story around pausing animated GIFs because it affects accessibility via MediaQueryData.disableAnimations. See #175516.

Today

Currently, it's possible to pause a gif using TickerProvider. However, if paused on initial load, the first frame will never display, and I believe that's a bug.

TickerMode(
  // Pauses the gif, but if set to false on first load, the first frame never loads.
  enabled: false,
  child: Image(image: myAnimatedGif),
),

Currently disableAnimations has no effect:

MediaQuery(
  // Currently has no effect on the Image, until this PR.
  data: MediaQueryData(disableAnimations: true),
  child: Image(image: myAnimatedGif),
),

With this PR

MediaQueryData.disableAnimations can be used to pause a gif in the same way that TickerMode can be used today.
If either MediaQuery.disableAnimations or TickerMode cause a gif to be paused on first load, it will show its first frame before pausing. This is potentially a breaking change.
The docs clearly explain this behavior and how to pause a gif.

Fixes #175516
Partial fix for #130976
Fixes Google b/419605327

…Image

…nd TickerMode

gemini-code-assist

Code Review

This pull request introduces functionality to pause animated GIFs, respecting TickerMode and MediaQueryData.disableAnimations. The implementation ensures that the first frame of a GIF is always displayed even if animations are disabled on load. The changes include updates to the Image widget's state management and documentation, along with comprehensive tests to verify the new behavior. My review focuses on improving documentation clarity and test correctness. I've pointed out a typo in a doc comment, a misleading comment in the new tests, and a typo in a test name.

gemini-code-assist · 2025-10-03T22:04:57Z

packages/flutter/lib/src/widgets/image.dart

+  /// when [TickerMode] is disabled or [MediaQuerData.disableAnimations] is
+  /// true.


There's a typo in MediaQuerData. It should be MediaQueryData. Correct documentation is important for maintainability.¹

/// when [TickerMode] is disabled or [MediaQueryData.disableAnimations] is

Style Guide References

Footnotes

Code should be optimized for readability. Clear and correct documentation improves readability. ↩

gemini-code-assist · 2025-10-03T22:04:58Z

packages/flutter/test/widgets/image_test.dart

+    // Another frame arriving also doesn't do anything, because
+    // disableAnimations is true.


This comment is slightly misleading. The second frame is processed and displayed, and only after that does the image stop listening for more frames. The test assertions correctly reflect this behavior (expect(lastFrame, 1)), but the comment suggests no update happens. A more accurate comment would improve clarity.¹

// The second frame is displayed, and then the image stops listening for // new frames since disableAnimations is true.

Style Guide References

Footnotes

Code should be optimized for readability. Clear and accurate comments are crucial for readability and maintainability. ↩

gemini-code-assist · 2025-10-03T22:04:58Z

packages/flutter/test/widgets/image_test.dart

+    // Another frame arriving also doesn't do anything, because
+    // disableAnimations is true.


This comment is slightly misleading, similar to the one in the disableAnimations test. The second frame is processed and displayed before the image stops listening for new frames. The test assertions correctly reflect this. A more accurate comment would improve clarity.¹

// The second frame is displayed, and then the image stops listening for // new frames since TickerMode is disabled.

Style Guide References

Footnotes

Code should be optimized for readability. Clear and accurate comments are crucial for readability and maintainability. ↩

gemini-code-assist · 2025-10-03T22:04:58Z

packages/flutter/test/widgets/image_test.dart

    expect(find.byType(Image), findsOneWidget);
  });

+  testWidgets('Keeps stream alive when anmiations are disabled', (WidgetTester tester) async {


There's a typo in the test name: "anmiations" should be "animations". Correct naming improves readability and maintainability.¹

testWidgets('Keeps stream alive when animations are disabled', (WidgetTester tester) async {

Style Guide References

Footnotes

Code should be optimized for readability. Correct naming in tests improves readability and makes test failures easier to understand. ↩

justinmc · 2025-10-03T22:07:52Z

@evantea Let me know if this won't solve your problem!

chunhtai · 2025-10-06T17:26:22Z

packages/flutter/lib/src/widgets/image.dart

+  bool _isPaused = false;
+
+  /// False when the class first is instantiated and true forever after the
+  /// first frame of the image is received.


What if image source changes?

I think you're right, if the image source changes we want to load the first frame of the new image. I'll do that.

This works now but it was a journey. I put everything related to source swapping into this into one commit: 3665a79. Summarizing:

When I first started looking at this, the behavior was that when I paused the image and then changed the image source, the Image would disappear (the first frame was never loaded).

I fixed that and it was pretty straightforward, but I noticed another problem: swapping the original source back in would advance it by one frame, not show the originally paused frame. If I switched back and forth between sources, they would each advance by one frame every time. Depending on the gif, this bug could be pretty noticeable.

To solve this, I implemented a cache of the most recent frame from each unique source.

Let me know if my cache solution is overkill and we should just accept the frame advancing bug. I'm happy with how the caching solution turned out but in retrospect I probably should have saved it for a separate PR if I had known it would take a day plus of hacking.

chunhtai · 2025-10-06T17:36:24Z

packages/flutter/lib/src/widgets/image.dart

  }

  void _handleImageFrame(ImageInfo imageInfo, bool synchronousCall) {
+    if (_hasReceivedFirstFrame && _isPaused) {


do we need to worry about first frame throws error?

I've rewritten this part, let me know if it's still a concern.

chunhtai · 2025-10-06T17:39:21Z

packages/flutter/lib/src/widgets/image.dart

    _resolveImage();

-    if (TickerMode.of(context)) {
+    _isPaused = !TickerMode.of(context) || (MediaQuery.maybeDisableAnimationsOf(context) ?? false);


not something needs to be addressed in this PR, but I am surprised maybeDisableAnimationsOf is not hooked up to the TickerMode directly

I've been thinking about them as two different things: MediaQueryData.disableAnimations is related to the system accessibility setting while TickerMode is about definitively disabling all animations. @evantea was unable to use TickerMode because it also disabled the fade animation that displayed the image, but that is not a problem for accessibility (see #175516 (comment)).

MediaQueryData.disableAnimations is related to the system accessibility setting

Yes, but what if a user toggle this setting and see all the animation is still animating. That feels bad. Right now we have to rely on developer or per widget to handle them seems not too scalable.

In the same time I wonder for the fade case, whether turning on disable animation should only turn off certain animation. Or maybe ticker may be used outside the just visual animation. Then in that case I agree hook up directly to ticker mode may not be a good idea. Maybe what we want is to hardcode all animation duration to zero if disableAnimations is on.

I guess we need to think hard about exactly which animations should be disabled and which (if any) shouldn't when disableAnimations is true. It is reasonable that maybe some Fade animations should be disabled.

The docs for disableAnimations do give me the impression that some animations will not be fully disabled:

Whether the platform is requesting that animations be disabled or reduced as much as possible.

See also:

dart:ui.PlatformDispatcher.accessibilityFeatures, where the setting originates.

evantea · 2025-10-06T20:08:57Z

@justinmc copied this commit into my local workspace, using only the "Remove Animations" system setting images, GIFs paused automatically (though only after rebuilding the view). Thanks for putting this together!

This is a combination of 5 commits, the older 4 being: WIP Image swapping WIP exploring swapping image sources and caching frames WIP swapping works without frame advancement, but some tests are failing WIP Works, but seems to be leaking

…(dispose)

justinmc · 2025-10-10T04:10:31Z

@chunhtai This is ready for re-review, but it seems to be failing a skwasm test in a way that I can't reproduce locally. See my comment at #176492 (comment). Since this is a P1, maybe I should split out the image source swapping fix into a follow-up PR. Interested in what you think.

chunhtai

Just one comment on the cache management, the rest LGTM

chunhtai · 2025-10-13T20:25:24Z

packages/flutter/lib/src/widgets/image.dart

+    if (oldImageInfo != null) {
+      SchedulerBinding.instance.addPostFrameCallback((Duration duration) {
+        // If oldImageInfo is still in the cache, then it will be disposed when
+        // the widget is disposed. Otherwise it has been evicted, so dispose it


any reason we don't dispose them now? also the current structure seems to make the _imageInfosCache to grow infinitely when Image source keep changing during the life time of this widget.

I refactored this to no longer need a cache.

As to why not dispose the image info immediately, I don't know! It seems to still work if I change it to dispose immediately, and all the tests even continue to pass.

I'll open a separate PR to try that out.

chunhtai · 2025-10-16T16:20:51Z

Hi @justinmc does this pr fixes #130976? I saw the pr is marked so in the description, but not sure whether that is the case

justinmc · 2025-10-17T23:27:24Z

@chunhtai I guess this only helps with Image, but that issue seems more broad. I will edit the description.

This reverts commit a28b26a. This should no longer be necessary if I can land a pending fix in Google's internal tests.

justinmc · 2025-11-10T17:19:53Z

I have a local commit to revert a28b26a that I will push as soon as my fix for the Google tests is merged.

justinmc · 2025-11-12T22:46:33Z

Google tests have been fixed in Google internal cl/829551684. Now triggering a re-run to confirm that they pass with this PR applied.

chunhtai · 2025-11-12T23:01:47Z

packages/flutter/lib/src/widgets/image.dart

-    } else {
+    _isPaused = !TickerMode.of(context) || (MediaQuery.maybeDisableAnimationsOf(context) ?? false);
+
+    if (_isPaused && _frameNumber != null) {


do you still need to keep track of number of frames? or can this be a boolean field?

I was about to change it but I realized it is used to give the frame number to frameBuilder: https://main-api.flutter.dev/flutter/widgets/ImageFrameBuilder.html

chunhtai

LGTM

justinmc added 6 commits October 2, 2025 10:46

Explain how to use TickerMode to pause animated gifs in the docs for …

f1f2354

…Image

Pause for MediaQuery.disableAnimations, too

2e2e03a

Same tests as TickerMode

d3bf79f

Loads first frame (TODO, test)

b65c11b

Test frame-by-frame for disableAnimations, and initial frame for it a…

97044a4

…nd TickerMode

Docs

e51c24a

justinmc self-assigned this Oct 3, 2025

github-actions bot added the framework flutter/packages/flutter repository. See also f: labels. label Oct 3, 2025

gemini-code-assist bot reviewed Oct 3, 2025

View reviewed changes

justinmc added 3 commits October 3, 2025 15:12

Docs typo

4770827

Fix bug where first 2 frames were rendered

9addf98

Spelling

a97ebc8

chunhtai self-requested a review October 6, 2025 16:42

Ignore leaks on tests that use stream completer

bc34df9

chunhtai reviewed Oct 6, 2025

View reviewed changes

Image swapping without frame advancement

3665a79

This is a combination of 5 commits, the older 4 being: WIP Image swapping WIP exploring swapping image sources and caching frames WIP swapping works without frame advancement, but some tests are failing WIP Works, but seems to be leaking

justinmc force-pushed the pause-gif branch from 8708dfb to 3665a79 Compare October 9, 2025 21:52

justinmc added 4 commits October 9, 2025 15:18

Trying to help pinpoint null check test failure message

f062cca

Fix wasm web failure.

b2c46c6

Well that didn't fix it. I'd guess the failing one is after SizedBox …

41fb8ed

…(dispose)

Merge branch 'master' into pause-gif

1dd0dbb

justinmc requested a review from chunhtai October 10, 2025 04:09

chunhtai reviewed Oct 13, 2025

View reviewed changes

chrisbobbe mentioned this pull request Oct 17, 2025

android: "Disable animations" isn't working for animated emoji zulip/zulip-flutter#1925

Closed

justinmc mentioned this pull request Oct 21, 2025

Expose iOS "Customize onscreen motion" accessibility settings #177330

Open

8 tasks

justinmc added 2 commits November 5, 2025 08:51

Analyzer

e190574

Merge branch 'master' into pause-gif

de7e2e1

chunhtai self-requested a review November 5, 2025 20:13

justinmc added 3 commits November 5, 2025 15:18

Merge branch 'master' into pause-gif

ad0981b

Merge branch 'master' into pause-gif

38076b4

Revert "Fix test detection."

8253d8f

This reverts commit a28b26a. This should no longer be necessary if I can land a pending fix in Google's internal tests.

Merge branch 'master' into pause-gif

d0f172e

chunhtai reviewed Nov 12, 2025

View reviewed changes

chunhtai approved these changes Nov 12, 2025

View reviewed changes

justinmc added the autosubmit Merge PR when tree becomes green via auto submit App label Nov 13, 2025

auto-submit bot added this pull request to the merge queue Nov 13, 2025

Merged via the queue into flutter:master with commit 89d59da Nov 13, 2025
76 checks passed

flutter-dashboard bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Nov 13, 2025

justinmc deleted the pause-gif branch November 13, 2025 20:28

engine-flutter-autoroll mentioned this pull request Nov 14, 2025

Roll Flutter from ee23168ddb5d to 35b8aca9c2ce (103 revisions) flutter/packages#10426

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Nov 14, 2025

89d59da9e Image GIF pausing (flutter/flutter#176492)

dcaa86d

engine-flutter-autoroll mentioned this pull request Nov 14, 2025

Roll Flutter from ee23168ddb5d to 1f69497f4fb6 (104 revisions) flutter/packages#10428

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Nov 14, 2025

89d59da9e Image GIF pausing (flutter/flutter#176492)

eef516a

engine-flutter-autoroll mentioned this pull request Nov 14, 2025

Roll Flutter from ee23168ddb5d to 4b55ea85fd18 (105 revisions) flutter/packages#10430

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Nov 14, 2025

89d59da9e Image GIF pausing (flutter/flutter#176492)

f868217

engine-flutter-autoroll mentioned this pull request Nov 14, 2025

Manual roll Flutter from ee23168ddb5d to 5798e1a28622 (106 revisions) flutter/packages#10432

Open

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Nov 14, 2025

89d59da9e Image GIF pausing (flutter/flutter#176492)

68641f4

Piinks mentioned this pull request Nov 14, 2025

Flutter Notable Commits - 2025 #161460

Open

engine-flutter-autoroll mentioned this pull request Nov 15, 2025

Roll Flutter from 9b5ad8031646 to 5ae70ee7c058 (112 revisions) flutter/packages#10437

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Nov 15, 2025

89d59da9e Image GIF pausing (flutter/flutter#176492)

c95bf9f

engine-flutter-autoroll mentioned this pull request Nov 15, 2025

Roll Flutter from 9b5ad8031646 to 5ae70ee7c058 (112 revisions) flutter/packages#10438

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Nov 15, 2025

89d59da9e Image GIF pausing (flutter/flutter#176492)

6d3a330

		/// when [TickerMode] is disabled or [MediaQuerData.disableAnimations] is
		/// true.

		// Another frame arriving also doesn't do anything, because
		// disableAnimations is true.

Image GIF pausing #176492

Image GIF pausing #176492

Conversation

justinmc commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Today

With this PR

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Oct 3, 2025

Choose a reason for hiding this comment

Style Guide References

Footnotes

Uh oh!

gemini-code-assist bot Oct 3, 2025

Choose a reason for hiding this comment

Style Guide References

Footnotes

Uh oh!

gemini-code-assist bot Oct 3, 2025

Choose a reason for hiding this comment

Style Guide References

Footnotes

Uh oh!

gemini-code-assist bot Oct 3, 2025

Choose a reason for hiding this comment

Style Guide References

Footnotes

Uh oh!

justinmc commented Oct 3, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evantea commented Oct 6, 2025

Uh oh!

justinmc commented Oct 10, 2025

Uh oh!

chunhtai left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chunhtai commented Oct 16, 2025

Uh oh!

justinmc commented Oct 17, 2025

Uh oh!

justinmc commented Nov 10, 2025

Uh oh!

justinmc commented Nov 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chunhtai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

justinmc commented Oct 3, 2025 •

edited

Loading