avoid_incorrect_image_opacity

v0.4.0 Warning Fix Widget Replacement

Flags Opacity widgets that wrap an Image widget as their child. The Image widget has a dedicated opacity parameter that is more efficient than wrapping it in a separate Opacity widget.

Why use this rule

Wrapping an Image in an Opacity widget creates an additional layer in the rendering pipeline, which triggers an offscreen buffer (saveLayer). The Image widget’s built-in opacity parameter applies opacity directly during painting, avoiding the extra compositing pass. This is both more performant and produces a flatter widget tree.

See also: Image | Opacity

Don’t

// Image wrapped in Opacity
Opacity(opacity: 0.5, child: Image.asset('assets/logo.png'));

// Image.network wrapped in Opacity
Opacity(
  opacity: 0.8,
  child: Image.network('https://example.com/image.png'),
);

Do

// Use Image's opacity parameter directly
Image.asset(
  'assets/logo.png',
  opacity: const AlwaysStoppedAnimation(0.5),
);

Image.network(
  'https://example.com/image.png',
  opacity: const AlwaysStoppedAnimation(0.8),
);

// Opacity wrapping a non-Image widget is fine
Opacity(opacity: 0.5, child: Text('Hello'));

Configuration

This rule is in the recommended preset, so it is on with preset: recommended or preset: opinionated. Add it to preset: core with avoid_incorrect_image_opacity: true.

To turn it off:

many_lints.yaml

rules:
  avoid_incorrect_image_opacity: false

To keep the rule on but skip certain paths, use per-rule exclude.

Related rules

• avoid_border_all — Use Border.fromBorderSide instead of Border.all for const support.
• avoid_expanded_as_spacer — Use Spacer instead of Expanded with an empty child.
• avoid_wrapping_in_padding — Avoid wrapping widgets that support padding in a Padding widget.
• prefer_align_over_container — Use Align instead of Container when only alignment is set.