Image.asset constructor

Image.asset(String name, { Key? key, AssetBundle? bundle, ImageFrameBuilder? frameBuilder, ImageErrorWidgetBuilder? errorBuilder, String? semanticLabel, bool excludeFromSemantics = false, double? scale, double? width, double? height, Color? color, Animation<double>? opacity, BlendMode? colorBlendMode, BoxFit? fit, AlignmentGeometry alignment = Alignment.center, ImageRepeat repeat = ImageRepeat.noRepeat, Rect? centerSlice, bool matchTextDirection = false, bool gaplessPlayback = false, bool isAntiAlias = false, String? package, FilterQuality filterQuality = FilterQuality.low, int? cacheWidth, int? cacheHeight, })

Creates a widget that displays an ImageStream obtained from an asset bundle. The key for the image is given by the name argument.

The package argument must be non-null when displaying an image from a package and null otherwise. See the Assets in packages section for details.

If the bundle argument is omitted or null, then the DefaultAssetBundle will be used.

By default, the pixel-density-aware asset resolution will be attempted. In addition:

• If the scale argument is provided and is not null, then the exact asset specified will be used. To display an image variant with a specific density, the exact path must be provided (e.g. images/2x/cat.png).

If excludeFromSemantics is true, then semanticLabel will be ignored.

If cacheWidth or cacheHeight are provided, they indicate to the engine that the image must be decoded at the specified size. The image will be rendered to the constraints of the layout or width and height regardless of these parameters. These parameters are primarily intended to reduce the memory usage of ImageCache.

Either the width and height arguments should be specified, or the widget should be placed in a context that sets tight layout constraints. Otherwise, the image dimensions will change as the image is loaded, which will result in ugly layout changes.

Use filterQuality to specify the rendering quality of the image.

{@tool snippet}

Suppose that the project's pubspec.yaml file contains the following:

flutter:
  assets:
    - images/cat.png
    - images/2x/cat.png
    - images/3.5x/cat.png

{@end-tool}

On a screen with a device pixel ratio of 2.0, the following widget would render the images/2x/cat.png file:

Image.asset('images/cat.png')

This corresponds to the file that is in the project's images/2x/ directory with the name cat.png (the paths are relative to the pubspec.yaml file).

On a device with a 4.0 device pixel ratio, the images/3.5x/cat.png asset would be used. On a device with a 1.0 device pixel ratio, the images/cat.png resource would be used.

The images/cat.png image can be omitted from disk (though it must still be present in the manifest). If it is omitted, then on a device with a 1.0 device pixel ratio, the images/2x/cat.png image would be used instead.

Assets in packages

To create the widget with an asset from a package, the package argument must be provided. For instance, suppose a package called my_icons has icons/heart.png .

{@tool snippet} Then to display the image, use:

Image.asset('icons/heart.png', package: 'my_icons')

{@end-tool}

Assets used by the package itself should also be displayed using the package argument as above.

If the desired asset is specified in the pubspec.yaml of the package, it is bundled automatically with the app. In particular, assets used by the package itself must be specified in its pubspec.yaml.

A package can also choose to have assets in its 'lib/' folder that are not specified in its pubspec.yaml. In this case for those images to be bundled, the app has to specify which ones to include. For instance a package named fancy_backgrounds could have:

lib/backgrounds/background1.png
lib/backgrounds/background2.png
lib/backgrounds/background3.png

To include, say the first image, the pubspec.yaml of the app should specify it in the assets section:

  assets:
    - packages/fancy_backgrounds/backgrounds/background1.png

The lib/ is implied, so it should not be included in the asset path.

See also:

• AssetImage, which is used to implement the behavior when the scale is omitted.
• ExactAssetImage, which is used to implement the behavior when the scale is present.
• flutter.dev/assets-and-images/, an introduction to assets in Flutter.

Implementation

Image.asset(
  String name, {
  super.key,
  AssetBundle? bundle,
  this.frameBuilder,
  this.errorBuilder,
  this.semanticLabel,
  this.excludeFromSemantics = false,
  double? scale,
  this.width,
  this.height,
  this.color,
  this.opacity,
  this.colorBlendMode,
  this.fit,
  this.alignment = Alignment.center,
  this.repeat = ImageRepeat.noRepeat,
  this.centerSlice,
  this.matchTextDirection = false,
  this.gaplessPlayback = false,
  this.isAntiAlias = false,
  String? package,
  this.filterQuality = FilterQuality.low,
  int? cacheWidth,
  int? cacheHeight,
})  : image = ResizeImage.resizeIfNeeded(
        cacheWidth,
        cacheHeight,
        scale != null
            ? ExactAssetImage(name,
                bundle: bundle, scale: scale, package: package)
            : AssetImage(name, bundle: bundle, package: package),
      ),
      loadingBuilder = null,
      assert(cacheWidth == null || cacheWidth > 0),
      assert(cacheHeight == null || cacheHeight > 0);