The Image widget supports loadingWidget, but backgroundImage does not support it consistently across all rendering paths. The decoration-based rendering path ignores loadingWidget, so no shimmer/placeholder can be shown while a remote background image loads. This behavior is also undocumented.
Describe the solution you'd like
Support loadingWidget on backgroundImage consistently across all rendering paths:
styles:
backgroundImage:
source: ${imageUrl}
fit: cover
loadingWidget:
Shape:
type: rectangle
styles:
backgroundColor: 0xff333333Also document the supported properties for backgroundImage.loadingWidget.
Describe alternatives you've considered
Replacing backgroundImage with a separate Image widget or a manual Stack — both work but require extra layout logic and duplicate framework functionality.
Additional context
Image.loadingWidget is already supported and used for shimmer placeholders. The framework's getImageAsWidget() path handles backgroundImage.loadingWidget, but getImageAsDecorated() does not. The behavior should be consistent or explicitly documented as limited to specific rendering paths.
The
Imagewidget supportsloadingWidget, butbackgroundImagedoes not support it consistently across all rendering paths. The decoration-based rendering path ignoresloadingWidget, so no shimmer/placeholder can be shown while a remote background image loads. This behavior is also undocumented.Describe the solution you'd like
Support
loadingWidgetonbackgroundImageconsistently across all rendering paths:Also document the supported properties for
backgroundImage.loadingWidget.Describe alternatives you've considered
Replacing
backgroundImagewith a separateImagewidget or a manualStack— both work but require extra layout logic and duplicate framework functionality.Additional context
Image.loadingWidgetis already supported and used for shimmer placeholders. The framework'sgetImageAsWidget()path handlesbackgroundImage.loadingWidget, butgetImageAsDecorated()does not. The behavior should be consistent or explicitly documented as limited to specific rendering paths.