> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions. # Flutter SVG Images: Bundle, Size, and Check Assets > Add an SVG asset to Flutter, match its bundle path, set widget dimensions, and check colours and semantics. Separate loading problems from unsupported artwork. Source: https://perfectvector.com/blog/flutter-svg-images Language: en Author: Irene Kim Published: 2026-09-13T08:00:00+09:00 To display an SVG asset in Flutter, add `flutter_svg`, declare the file in `pubspec.yaml`, and load that same path with `SvgPicture.asset`. Give the widget dimensions or suitable layout constraints, then inspect the artwork in your app. The [package's asset constructor](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/SvgPicture.asset.html) documents that loading route. Keep two questions separate: did the app load the intended file, and did the renderer reproduce the intended artwork? Re-exporting a drawing will not repair a misspelled asset key. Correcting the key will not simplify an unsupported effect. This walkthrough uses an original hills-and-sun illustration to make those checks manageable. The code follows the documented API; it is not a report of a compiled app test. ## Start with a small source you can inspect Create `assets/illustrations/hills.svg` in your Flutter project: ```svg ``` The source has two overlapping triangular hills and a detached amber sun. It uses explicit fills, has no text or linked images, and leaves a visible gap between the sun and the hills. Those details give you a short acceptance list when checking the app. Keep a copy of this simple file while introducing your own artwork later. If the small source works but the replacement fails, compare their structure before changing the entire loading setup. ![Conceptual route from a hills-and-sun SVG file through an asset folder to the same artwork inside a display frame](https://perfectvector.com/blog/flutter-svg-images/asset-bundle-widget.webp) *Conceptual illustration: source artwork, asset packaging, and widget display are separate checkpoints.* A Flutter SVG asset is also a different delivery route from Android VectorDrawable XML. If your destination is a native Android drawable, use the [Android VectorDrawable preparation guide](https://perfectvector.com/blog/convert-png-to-android-vector-drawable) instead of treating the two file formats as interchangeable. ## Add the package and declare the exact file From the Flutter project's root, use the [official installation command](https://pub.dev/packages/flutter_svg/install): ```bash flutter pub add flutter_svg ``` Then add this asset entry under the existing `flutter:` section of `pubspec.yaml`: ```yaml flutter: assets: - assets/illustrations/hills.svg ``` Merge the entry into your current configuration rather than creating a second `flutter:` section. Keep the indentation shown. Flutter's [asset documentation](https://docs.flutter.dev/ui/assets/assets-and-images) defines these paths relative to `pubspec.yaml` and explains how the listed files enter the app bundle. Use the same spelling, capitalization, and directory structure in the filename, declaration, and Dart call. For this first check, an explicit file entry is easier to compare than a broad folder entry. If you later declare directories, Flutter documents that a directory entry covers its direct files; nested directories need their own entries. After changing the asset configuration, rebuild and run the app with your normal development workflow. Do not assume that a file visible in your editor is already included in the app you are looking at. ## Load the artwork into a defined box Add these imports to the Dart file containing your widget: ```dart import 'package:flutter/material.dart'; import 'package:flutter_svg/flutter_svg.dart'; ``` Place this widget in a suitable part of your screen: ```dart SvgPicture.asset( 'assets/illustrations/hills.svg', width: 128, height: 96, fit: BoxFit.contain, semanticsLabel: 'Sun above two hills', errorBuilder: (context, error, stackTrace) => const Text('Illustration unavailable'), ) ``` The box follows the source's proportions. Inspect the detached sun, both hill colours, and the outside margins before trying a smaller size. Then use the dimensions required by your actual component; the numbers above are an example, not a minimum size or a performance recommendation. The [constructor documentation](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/SvgPicture.asset.html) recommends explicit dimensions or tight layout constraints so loading does not unexpectedly change the layout. If the artwork looks too small inside the box, inspect blank space in its `viewBox` as well as the widget's dimensions. The label describes this standalone picture's purpose. The [semanticsLabel API](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/semanticsLabel.html) connects it to the picture's semantic label. For a decorative image beside text that already conveys the meaning, consider excluding the picture from semantics instead. The constructor's `excludeFromSemantics` option takes precedence over its label. Review the whole component's spoken meaning rather than labeling every shape separately. ## Distinguish a loading placeholder from an error A loading indicator is not proof that an SVG was accepted. The package provides `placeholderBuilder` for the acquisition or decoding period, while the current [errorBuilder API](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/errorBuilder.html) supplies a widget when image loading fails. The example above uses a short text fallback. During development, deliberately change the Dart path to a nonexistent filename and check that you can recognize the failure. Restore the correct path before continuing. This tests your failure presentation without changing the drawing itself. Then test your real source. If it still fails, inspect the diagnostic output and compare the declared path first. A network example that happens to display a different SVG does not establish that your local file is bundled or that its features are supported. ## Decide whether to preserve the palette or apply a tint Leave `colorFilter` unset when the hills need to stay teal and navy with an amber sun. For a deliberately single-colour treatment, add a filter such as: ```dart colorFilter: const ColorFilter.mode( Color(0xFF175CD3), BlendMode.srcIn, ), ``` The package documents this tinting pattern. Flutter's [BlendMode reference](https://api.flutter.dev/flutter/dart-ui/BlendMode.html) explains that `srcIn` uses the destination's opacity while ignoring its colour channels. A uniform tint therefore removes the source palette distinction; it is a design choice, not a colour-preservation repair. For the hills, check whether losing the contrast between the two overlapping triangles makes the illustration harder to read. Keep the original palette if those regions need to remain distinct. The package also documents `ColorMapper` for selective substitutions, but start with the simpler unfiltered case while diagnosing a mismatch. ## Simplify features only after the file loads The [flutter\_svg documentation](https://pub.dev/packages/flutter_svg) recommends presentation attributes when exporting from Illustrator because CSS support is incomplete, and embedded rather than externally linked images. It also provides a compiler-based compatibility check. Follow that check in your own Flutter/Dart environment when a complex asset needs investigation. A browser preview is a useful reference for the intended appearance; it does not prove that every SVG feature will render identically through the package. Keep the original artwork and simplify a copy one change at a time. | What you observe | Next comparison | | ----------------------------------------------------- | ------------------------------------------------------- | | Nothing appears | Asset key, declaration, fallback, and diagnostic output | | The simple hills display but another drawing does not | Source structure and renderer compatibility | | All regions become one colour | Widget colour filter before editing source fills | | The drawing is tiny within its box | ViewBox whitespace and layout constraints | | Text differs or disappears | Font dependencies and the intended text treatment | | A detail is missing at component size | Original geometry, overlaps, and available space | If the source contains lettering, decide whether it should remain app text or fixed artwork. The [SVG font-change guide](https://perfectvector.com/blog/svg-font-changes) explains why appearance can depend on text and font handling. Do not trace a label just to solve an asset-path problem. For a family of UI assets, compare their visual size and spacing together. The [UI-kit icon preparation guide](https://perfectvector.com/blog/convert-png-icons-to-svg-for-ui-kit) helps with that consistency check. ## Use vectorization when the source needs recovery Keep a clean existing SVG. A photograph or textured background may be better delivered as an appropriate raster asset; changing the extension does not make it useful vector geometry. If a simple illustration survives only as a rough PNG, PerfectVector's [PNG-to-SVG workflow](https://perfectvector.com/convert-png-to-svg) can help prepare an editable candidate. Crop to the artwork, inspect the preview for missing shapes and unwanted background regions, and download the SVG. Add that file to the app bundle and repeat the loading, palette, size, and semantics checks. For the hills example, look for the detached sun and the separation between the two coloured slopes. Confirm the file contains the structure you intended; the [embedded-raster guide](https://perfectvector.com/blog/svg-contains-raster-image) explains why an SVG wrapper can still hold pixels. Judge the asset in the app before choosing an optimization strategy. This workflow makes no general promise that an SVG is smaller or faster than a PNG. If you reuse the artwork in a .NET MAUI app, follow the [MAUI source-to-PNG workflow](https://perfectvector.com/blog/svg-in-dotnet-maui). The project keeps the SVG master while the view references a PNG prepared during the build. ## FAQ **How do I add an SVG image to Flutter?** Add flutter\_svg, declare the SVG asset in pubspec.yaml, and load the matching path with SvgPicture.asset. Set dimensions or appropriate constraints and inspect the result. **Why does my local SVG not appear?** Check the asset declaration, exact path, loading error, and layout first. If a simple source works, compare the failing artwork's structure and supported features. **Why did all the colours become the same?** A uniform srcIn colour filter replaces the visible palette with its tint. Remove that filter when the original colours should remain distinct. **Must I turn a PNG into SVG for Flutter?** No. Use a suitable raster asset when it fits the artwork. Vectorization is optional when recovering editable shapes from a simple raster source. ## Sources 1. [flutter\_svg — Installing](https://pub.dev/packages/flutter_svg/install) — Package installation and Dart import. 2. [Flutter — Adding assets and images](https://docs.flutter.dev/ui/assets/assets-and-images) — Asset declarations, paths, and bundling. 3. [flutter\_svg — SvgPicture.asset](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/SvgPicture.asset.html) — Asset loading, dimensions, fitting, and semantics controls. 4. [flutter\_svg — errorBuilder](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/errorBuilder.html) — Failure presentation distinct from loading placeholders. 5. [flutter\_svg — semanticsLabel](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/semanticsLabel.html) — The picture's semantic purpose. 6. [Flutter — BlendMode](https://api.flutter.dev/flutter/dart-ui/BlendMode.html) — The opacity-based srcIn colour treatment. 7. [flutter\_svg — Package documentation](https://pub.dev/packages/flutter_svg) — Tinting, selective colour mapping, export guidance, and compatibility checks. *** Start with one declared asset and check its path, palette, size, and meaning in your app. If a raster illustration needs recovery, [prepare an SVG candidate](https://perfectvector.com/convert-png-to-svg), inspect its shapes, and run the same checks before adding it to your asset family. ## Explore - [Read the HTML article](https://perfectvector.com/blog/flutter-svg-images) - [SVG in SwiftUI: Add Assets and Control Their Color](https://perfectvector.com/blog/svg-in-swiftui.md) - [SVG in WPF: Choose a Renderer or a XAML Drawing](https://perfectvector.com/blog/svg-in-wpf.md) - [Product facts](https://perfectvector.com/product-facts.md) - [FAQ](https://perfectvector.com/faq.md) - [Pricing and credits](https://perfectvector.com/pricing.md)