SvgPicture.asset constructor

SvgPicture.asset(
  1. String assetName, {
  2. Key? key,
  3. bool matchTextDirection = false,
  4. AssetBundle? bundle,
  5. String? package,
  6. double? width,
  7. double? height,
  8. BoxFit fit = BoxFit.contain,
  9. AlignmentGeometry alignment = Alignment.center,
  10. bool allowDrawingOutsideViewBox = false,
  11. WidgetBuilder? placeholderBuilder,
  12. Color? color,
  13. BlendMode colorBlendMode = BlendMode.srcIn,
  14. String? semanticsLabel,
  15. bool excludeFromSemantics = false,
  16. Clip clipBehavior = Clip.hardEdge,
  17. bool cacheColorFilter = false,
  18. Color? currentColor,
})

Instantiates a widget that renders an SVG picture from an AssetBundle.

The key will be derived from the assetName, package, and bundle arguments. The package argument must be non-null when displaying an SVG from a package and null otherwise. See the Assets in packages section for details.

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.

If matchTextDirection is set to true, the picture will be flipped horizontally in TextDirection.rtl contexts.

The allowDrawingOutsideOfViewBox parameter should be used with caution - if set to true, it will not clip the canvas used internally to the view box, meaning the picture may draw beyond the intended area and lead to undefined behavior or additional memory overhead.

A custom placeholderBuilder can be specified for cases where decoding or acquiring data may take a noticeably long time.

The color and colorBlendMode arguments, if specified, will be used to set a ColorFilter on any Paints created for this drawing.

The currentColor argument, if provided, will override the default color of any SVG element that inherits its color.

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.svg .

Then to display the image, use:

SvgPicture.asset('icons/heart.svg', package: 'my_icons')

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.svg
lib/backgrounds/background2.svg
lib/backgrounds/background3.svg

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.svg

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

See also:

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

If excludeFromSemantics is true, then semanticLabel will be ignored.

Implementation

SvgPicture.asset(
  String assetName, {
  Key? key,
  this.matchTextDirection = false,
  AssetBundle? bundle,
  String? package,
  this.width,
  this.height,
  this.fit = BoxFit.contain,
  this.alignment = Alignment.center,
  this.allowDrawingOutsideViewBox = false,
  this.placeholderBuilder,
  Color? color,
  BlendMode colorBlendMode = BlendMode.srcIn,
  this.semanticsLabel,
  this.excludeFromSemantics = false,
  this.clipBehavior = Clip.hardEdge,
  this.cacheColorFilter = false,
  this.currentColor,
})  : pictureProvider = ExactAssetPicture(
        allowDrawingOutsideViewBox == true
            ? svgStringDecoderOutsideViewBoxBuilder
            : svgStringDecoderBuilder,
        assetName,
        bundle: bundle,
        package: package,
        colorFilter: svg.cacheColorFilterOverride ?? cacheColorFilter
            ? _getColorFilter(color, colorBlendMode)
            : null,
      ),
      colorFilter = _getColorFilter(color, colorBlendMode),
      super(key: key);