Skip to content

feat: Add placeholder to DecorationImage - #191528

Merged
auto-submit[bot] merged 4 commits into
flutter:masterfrom
rkishan516:decoration-image-placeholder
Sep 2, 2026
Merged

feat: Add placeholder to DecorationImage#191528
auto-submit[bot] merged 4 commits into
flutter:masterfrom
rkishan516:decoration-image-placeholder

Conversation

@rkishan516

@rkishan516 rkishan516 commented Aug 22, 2026

Copy link
Copy Markdown
Contributor

This PR adds an optional placeholder to DecorationImage, so a box decoration can show a cheap, locally available image while its main image is still loading instead of rendering nothing.

_DecorationImagePainter resolves placeholder only while image has not resolved yet, and paints whichever of the two is available. As soon as image arrives, the placeholder's stream listener is removed and its ImageInfo is disposed, so the placeholder does not outlive its usefulness. Late placeholder frames that arrive after the image has loaded are disposed immediately.

Fixes: #187906

Pre-launch Checklist

  • I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
  • I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools.
  • I read the [Tree Hygiene] wiki page, which explains my responsibilities.
  • I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement].
  • I signed the [CLA].
  • I listed at least one issue that this PR fixes in the description above.
  • I updated/added relevant documentation (doc comments with ///).
  • I added new tests to check the change I am making, or this PR is [test-exempt].
  • I followed the [breaking change policy] and added [Data Driven Fixes] where supported.
  • All existing and new tests are passing.

@rkishan516
feat: Add placeholder to DecorationImage
49fbb68 
Adds an optional `placeholder` image provider to `DecorationImage`. The
placeholder is painted while `image` is loading, and its stream listener
and image handle are released as soon as `image` becomes available.
@flutter-dashboard flutter-dashboard Bot added the CICD Run CI/CD label Aug 22, 2026
@github-actions github-actions Bot added the framework flutter/packages/flutter repository. See also f: labels. label Aug 22, 2026
gemini-code-assist[bot]
gemini-code-assist Bot reviewed Aug 22, 2026
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds a placeholder property to DecorationImage to display a temporary image while the main image loads, updating the painter, equality checks, and string representation accordingly. Feedback suggests optimizing _disposePlaceholder by checking if _placeholderStream is null before instantiating a new ImageStreamListener to prevent redundant allocations.

Comment thread packages/flutter/lib/src/painting/decoration_image.dart
Comment on lines +478 to +485
void _disposePlaceholder() {
_placeholderStream?.removeListener(
ImageStreamListener(_handlePlaceholderImage, onError: _details.onError),
);
_placeholderStream = null;
_placeholderImage?.dispose();
_placeholderImage = null;
}

@gemini-code-assist gemini-code-assist Bot Aug 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

In _disposePlaceholder(), we can avoid unnecessarily instantiating a new ImageStreamListener when _placeholderStream is null. Since _disposePlaceholder() is called on every frame of the main image (e.g., for animated GIFs via _handleImage), adding a null check on _placeholderStream before creating the listener avoids redundant allocations.

  void _disposePlaceholder() {
    if (_placeholderStream != null) {
      _placeholderStream!.removeListener(
        ImageStreamListener(_handlePlaceholderImage, onError: _details.onError),
      );
      _placeholderStream = null;
    }
    _placeholderImage?.dispose();
    _placeholderImage = null;
  }

justinmc
justinmc reviewed Aug 25, 2026
View reviewed changes

@justinmc justinmc left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Quick drive by review: could/should this be done with something like FadeInImage?

@rkishan516

rkishan516 commented Aug 27, 2026

Copy link
Copy Markdown
Contributor Author

Quick drive by review: could/should this be done with something like FadeInImage?

Hey @justinmc , its just a addition if someone doesn't want fade affect.

justinmc
justinmc approved these changes Sep 1, 2026
View reviewed changes

@justinmc justinmc left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍

@justinmc justinmc added the autosubmit Merge PR when tree becomes green via auto submit App label Sep 1, 2026
@auto-submit auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Sep 1, 2026
@auto-submit

auto-submit Bot commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

autosubmit label was removed for flutter/flutter/191528, because The base commit of the PR is older than 7 days and can not be merged. Please merge the latest changes from the main into this branch and resubmit the PR.

@victorsanni victorsanni added CICD Run CI/CD autosubmit Merge PR when tree becomes green via auto submit App and removed CICD Run CI/CD labels Sep 2, 2026
@auto-submit auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Sep 2, 2026
@auto-submit

auto-submit Bot commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

autosubmit label was removed for flutter/flutter/191528, because - The status or check suite Dashboard Checks has failed. Please fix the issues identified (or deflake) before re-applying this label.

@victorsanni victorsanni added CICD Run CI/CD and removed CICD Run CI/CD labels Sep 2, 2026
@victorsanni victorsanni added CICD Run CI/CD and removed CICD Run CI/CD labels Sep 2, 2026
@rkishan516 rkishan516 added the autosubmit Merge PR when tree becomes green via auto submit App label Sep 2, 2026
@auto-submit
auto-submit Bot added this pull request to the merge queue Sep 2, 2026
Merged via the queue into flutter:master with commit ce1f5ff Sep 2, 2026
29 checks passed
@flutter-dashboard flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Sep 2, 2026
This was referenced Sep 2, 2026
Closed
Merged
Closed
Closed
Closed
Closed
auto-submit Bot pushed a commit to flutter/packages that referenced this pull request Sep 4, 2026
@engine-flutter-autoroll
Roll Flutter from 0cbd1a4be0a4 to 70797e15325e (27 revisions) (#12727)
1240bb5 
flutter/flutter@0cbd1a4...70797e1

2026-09-02 [email protected] [analysis] Upgrade package:analyzer to 14.3.0 and enable custom plugin compilation (flutter/flutter#191590)
2026-09-02 [email protected] Roll Dart SDK from d8d7869d8031 to 9a8fbde80f6c (1 revision) (flutter/flutter#192179)
2026-09-02 [email protected] Roll Skia from dec311244db4 to ae22da2e8308 (1 revision) (flutter/flutter#192177)
2026-09-02 [email protected] [tool] Migrate DoctorCommand to modular dependency injection (flutter/flutter#190758)
2026-09-02 [email protected] Roll Skia from 482b7e285244 to dec311244db4 (3 revisions) (flutter/flutter#192161)
2026-09-02 [email protected] Roll Skia from 28447e9fb8d5 to 482b7e285244 (3 revisions) (flutter/flutter#192157)
2026-09-02 [email protected] feat: Add placeholder to DecorationImage (flutter/flutter#191528)
2026-09-02 [email protected] [Android] Do not schedule engine frames on a detached FlutterJNI (flutter/flutter#191204)
2026-09-02 [email protected] Roll Skia from 3a242fb7cdb3 to 28447e9fb8d5 (1 revision) (flutter/flutter#192145)
2026-09-02 [email protected] Roll Dart SDK from 9164def35347 to d8d7869d8031 (2 revisions) (flutter/flutter#192144)
2026-09-02 [email protected] Add FadeInImageTransition.fadeInOver to fade the image in over the placeholder (flutter/flutter#186246)
2026-09-02 [email protected] Roll Skia from 63d13ec4df6d to 3a242fb7cdb3 (9 revisions) (flutter/flutter#192138)
2026-09-02 [email protected] [flutter_tools] Add --no-plugins flag and disable plugins for benchmark (flutter/flutter#192129)
2026-09-02 [email protected] [tool] Migrate ChannelCommand to modular dependency injection (flutter/flutter#190751)
2026-09-01 [email protected] Add mouseCursor to RawScrollbar (flutter/flutter#185750)
2026-09-01 [email protected] Fix self-comparison and assert typos in TestSemantics (flutter/flutter#191938)
2026-09-01 [email protected] [Linux] Wait for frames to be rendered before using them in another context (flutter/flutter#192094)
2026-09-01 [email protected] [wimp] Turn on multithreading for wimp. (flutter/flutter#191747)
2026-09-01 [email protected] Roll Skia from 3911a1fe7f7a to 63d13ec4df6d (6 revisions) (flutter/flutter#192125)
2026-09-01 [email protected] Remove the redundant flutter/shell/platform/android:robolectric_tests build target (flutter/flutter#192117)
2026-09-01 [email protected] [iOS] Preserve semantics parents after reparenting (flutter/flutter#189686)
2026-09-01 [email protected] [flutter_tools] Report preview reload timing analytics in LspPreviewDetector (flutter/flutter#192120)
2026-09-01 [email protected] [flutter_tools] Implement Templates slice and flutter create integration (flutter/flutter#191748)
2026-09-01 [email protected] Uiscene migrate add2app hosts (flutter/flutter#191847)
2026-09-01 [email protected] Roll Packages from d642322 to 7a7912f (8 revisions) (flutter/flutter#192119)
2026-09-01 [email protected] [web] Anchor flt-semantics-host at 0,0 to fix WebKit semantics offset (flutter/flutter#190486)
2026-09-01 [email protected] Replace Shell::WaitForFirstFrame with an asynchronous API that matches the Shell threading model (flutter/flutter#191841)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
@justinmc justinmc mentioned this pull request Sep 4, 2026
Open
victorsanni pushed a commit to victorsanni/packages that referenced this pull request Sep 9, 2026
@engine-flutter-autoroll @victorsanni
Roll Flutter from 0cbd1a4be0a4 to 70797e15325e (27 revisions) (flutte…
2822f8e 
…r#12727)

flutter/flutter@0cbd1a4...70797e1

2026-09-02 [email protected] [analysis] Upgrade package:analyzer to 14.3.0 and enable custom plugin compilation (flutter/flutter#191590)
2026-09-02 [email protected] Roll Dart SDK from d8d7869d8031 to 9a8fbde80f6c (1 revision) (flutter/flutter#192179)
2026-09-02 [email protected] Roll Skia from dec311244db4 to ae22da2e8308 (1 revision) (flutter/flutter#192177)
2026-09-02 [email protected] [tool] Migrate DoctorCommand to modular dependency injection (flutter/flutter#190758)
2026-09-02 [email protected] Roll Skia from 482b7e285244 to dec311244db4 (3 revisions) (flutter/flutter#192161)
2026-09-02 [email protected] Roll Skia from 28447e9fb8d5 to 482b7e285244 (3 revisions) (flutter/flutter#192157)
2026-09-02 [email protected] feat: Add placeholder to DecorationImage (flutter/flutter#191528)
2026-09-02 [email protected] [Android] Do not schedule engine frames on a detached FlutterJNI (flutter/flutter#191204)
2026-09-02 [email protected] Roll Skia from 3a242fb7cdb3 to 28447e9fb8d5 (1 revision) (flutter/flutter#192145)
2026-09-02 [email protected] Roll Dart SDK from 9164def35347 to d8d7869d8031 (2 revisions) (flutter/flutter#192144)
2026-09-02 [email protected] Add FadeInImageTransition.fadeInOver to fade the image in over the placeholder (flutter/flutter#186246)
2026-09-02 [email protected] Roll Skia from 63d13ec4df6d to 3a242fb7cdb3 (9 revisions) (flutter/flutter#192138)
2026-09-02 [email protected] [flutter_tools] Add --no-plugins flag and disable plugins for benchmark (flutter/flutter#192129)
2026-09-02 [email protected] [tool] Migrate ChannelCommand to modular dependency injection (flutter/flutter#190751)
2026-09-01 [email protected] Add mouseCursor to RawScrollbar (flutter/flutter#185750)
2026-09-01 [email protected] Fix self-comparison and assert typos in TestSemantics (flutter/flutter#191938)
2026-09-01 [email protected] [Linux] Wait for frames to be rendered before using them in another context (flutter/flutter#192094)
2026-09-01 [email protected] [wimp] Turn on multithreading for wimp. (flutter/flutter#191747)
2026-09-01 [email protected] Roll Skia from 3911a1fe7f7a to 63d13ec4df6d (6 revisions) (flutter/flutter#192125)
2026-09-01 [email protected] Remove the redundant flutter/shell/platform/android:robolectric_tests build target (flutter/flutter#192117)
2026-09-01 [email protected] [iOS] Preserve semantics parents after reparenting (flutter/flutter#189686)
2026-09-01 [email protected] [flutter_tools] Report preview reload timing analytics in LspPreviewDetector (flutter/flutter#192120)
2026-09-01 [email protected] [flutter_tools] Implement Templates slice and flutter create integration (flutter/flutter#191748)
2026-09-01 [email protected] Uiscene migrate add2app hosts (flutter/flutter#191847)
2026-09-01 [email protected] Roll Packages from d642322 to 7a7912f (8 revisions) (flutter/flutter#192119)
2026-09-01 [email protected] [web] Anchor flt-semantics-host at 0,0 to fix WebKit semantics offset (flutter/flutter#190486)
2026-09-01 [email protected] Replace Shell::WaitForFirstFrame with an asynchronous API that matches the Shell threading model (flutter/flutter#191841)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
victorsanni pushed a commit to victorsanni/packages that referenced this pull request Sep 9, 2026
@engine-flutter-autoroll @victorsanni
Roll Flutter from 0cbd1a4be0a4 to 70797e15325e (27 revisions) (flutte…
2ee1685 
…r#12727)

flutter/flutter@0cbd1a4...70797e1

2026-09-02 [email protected] [analysis] Upgrade package:analyzer to 14.3.0 and enable custom plugin compilation (flutter/flutter#191590)
2026-09-02 [email protected] Roll Dart SDK from d8d7869d8031 to 9a8fbde80f6c (1 revision) (flutter/flutter#192179)
2026-09-02 [email protected] Roll Skia from dec311244db4 to ae22da2e8308 (1 revision) (flutter/flutter#192177)
2026-09-02 [email protected] [tool] Migrate DoctorCommand to modular dependency injection (flutter/flutter#190758)
2026-09-02 [email protected] Roll Skia from 482b7e285244 to dec311244db4 (3 revisions) (flutter/flutter#192161)
2026-09-02 [email protected] Roll Skia from 28447e9fb8d5 to 482b7e285244 (3 revisions) (flutter/flutter#192157)
2026-09-02 [email protected] feat: Add placeholder to DecorationImage (flutter/flutter#191528)
2026-09-02 [email protected] [Android] Do not schedule engine frames on a detached FlutterJNI (flutter/flutter#191204)
2026-09-02 [email protected] Roll Skia from 3a242fb7cdb3 to 28447e9fb8d5 (1 revision) (flutter/flutter#192145)
2026-09-02 [email protected] Roll Dart SDK from 9164def35347 to d8d7869d8031 (2 revisions) (flutter/flutter#192144)
2026-09-02 [email protected] Add FadeInImageTransition.fadeInOver to fade the image in over the placeholder (flutter/flutter#186246)
2026-09-02 [email protected] Roll Skia from 63d13ec4df6d to 3a242fb7cdb3 (9 revisions) (flutter/flutter#192138)
2026-09-02 [email protected] [flutter_tools] Add --no-plugins flag and disable plugins for benchmark (flutter/flutter#192129)
2026-09-02 [email protected] [tool] Migrate ChannelCommand to modular dependency injection (flutter/flutter#190751)
2026-09-01 [email protected] Add mouseCursor to RawScrollbar (flutter/flutter#185750)
2026-09-01 [email protected] Fix self-comparison and assert typos in TestSemantics (flutter/flutter#191938)
2026-09-01 [email protected] [Linux] Wait for frames to be rendered before using them in another context (flutter/flutter#192094)
2026-09-01 [email protected] [wimp] Turn on multithreading for wimp. (flutter/flutter#191747)
2026-09-01 [email protected] Roll Skia from 3911a1fe7f7a to 63d13ec4df6d (6 revisions) (flutter/flutter#192125)
2026-09-01 [email protected] Remove the redundant flutter/shell/platform/android:robolectric_tests build target (flutter/flutter#192117)
2026-09-01 [email protected] [iOS] Preserve semantics parents after reparenting (flutter/flutter#189686)
2026-09-01 [email protected] [flutter_tools] Report preview reload timing analytics in LspPreviewDetector (flutter/flutter#192120)
2026-09-01 [email protected] [flutter_tools] Implement Templates slice and flutter create integration (flutter/flutter#191748)
2026-09-01 [email protected] Uiscene migrate add2app hosts (flutter/flutter#191847)
2026-09-01 [email protected] Roll Packages from d642322 to 7a7912f (8 revisions) (flutter/flutter#192119)
2026-09-01 [email protected] [web] Anchor flt-semantics-host at 0,0 to fix WebKit semantics offset (flutter/flutter#190486)
2026-09-01 [email protected] Replace Shell::WaitForFirstFrame with an asynchronous API that matches the Shell threading model (flutter/flutter#191841)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@justinmc justinmc justinmc approved these changes
@victorsanni victorsanni victorsanni approved these changes
+1 more reviewer
@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

CICD Run CI/CD framework flutter/packages/flutter repository. See also f: labels.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add placeholder to DecorationImage when image is a network image.

3 participants

@rkishan516 @justinmc @victorsanni