> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.
# SVG in .NET MAUI: Keep SVG, Reference the PNG
> Add an SVG to a .NET MAUI project, reference its PNG output, and separate BaseSize from layout size. Check filenames, image metadata, and the finished artwork.
Source: https://perfectvector.com/blog/svg-in-dotnet-maui
Language: en
Author: Claire Yoon
Published: 2026-09-15T08:00:00+09:00
Updated: 2026-09-15T08:00:00+09:00
To use SVG in .NET MAUI's bundled-image workflow, keep the SVG in your project and reference its generated **PNG name** from XAML or C#. MAUI processes the vector source during the build. An `Image` pointing at `compass.png` can therefore be correct even when the file you added is `compass.svg`. [Microsoft's project-image guide](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/images/images) documents this conversion.
That explains the filename, but it leaves a design question: what size should MAUI generate, and what should you inspect afterward? Follow one small compass emblem through the source, project metadata, and display declaration.
## Follow the source through the build
The editable SVG and the packaged image have different jobs. Keep the source so you can adjust its shapes, whitespace, or colors later. Use the generated name in the view that displays it.
| Stage | Compass example | Your decision |
| -------------- | -------------------------------- | ------------------------------------------------------------------ |
| Artwork source | `Resources/Images/compass.svg` | Set the drawing bounds and preserve the ring opening. |
| Project item | `MauiImage` with a baseline size | Choose the image dimensions used to derive target-density outputs. |
| View | `Image Source="compass.png"` | Choose the display area and scaling behavior. |
The [Image control documentation](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/image) describes the target-density images entering the app package and the operating system selecting an appropriate resolution. Keeping an SVG master does not mean this particular workflow delivers a live SVG document to the view.
*Illustration of the bundled-image workflow. The SVG remains the editable source; the build prepares PNG images for the app.*
## Add a small SVG with clear bounds
Save this original example as `Resources/Images/compass.svg`:
```xml
```
The ring leaves a transparent center, and the coral needle is a separate shape. Those details give you something specific to check after import. The declared dimensions and square `viewBox` also make the intended framing clear. See the [SVG file guide](https://perfectvector.com/blog/what-is-an-svg-file) for how vector geometry differs from a bitmap embedded inside an SVG wrapper.
In your project, confirm that the file has the `MauiImage` build action. Microsoft documents the `Resources/Images` folder as the normal location. Before adding XML, inspect the existing project items: your project may already include that folder with a wildcard. [Project-image setup](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/images/images) explains placement and build action.
### Update an existing item once
If an existing `MauiImage` wildcard already includes the compass file, put this metadata update after that inclusion:
```xml
```
`Update` changes metadata on an item that already exists. It does not add a missing file to the item list. If your project has no matching inclusion, add the file once with the `MauiImage` build action or an explicit `Include` instead. Microsoft's [MSBuild Item reference](https://learn.microsoft.com/en-us/visualstudio/msbuild/item-element-msbuild) distinguishes these operations.
This avoids a tempting repair: repeatedly adding `Include` entries while debugging a missing image. First establish whether the file is included, then change its metadata.
## Reference the PNG and set the display area
Place this declaration inside an existing MAUI page or layout:
```xml
```
The `.png` extension is intentional. The width and height request a square display area; `AspectFit` keeps the whole image visible inside it. If your illustration is rectangular, use a display area suited to it rather than stretching it to fill a square. Microsoft's [Image scaling reference](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/image#control-image-scaling) distinguishes fitting, cropping, and stretching.
The compass code is an original setup example, not a recorded device-rendering test. Build it in your own target project and inspect the resulting view. A correct filename alone cannot establish that your particular artwork renders as intended.
## BaseSize and layout size solve different problems
`BaseSize="48,48"` supplies the baseline dimensions from which MAUI derives density-specific images. Without an explicit base size, MAUI uses the SVG's own dimensions. Microsoft documents both rules in [Resize an image](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/images/images#resize-an-image).
In this example, the source drawing uses a 96-by-96 coordinate space, while the requested baseline and view are 48 by 48. Those numbers are deliberate authoring choices, not measured output dimensions from a build. The ring should retain its proportions when scaled.
If you later use the same emblem in a much larger view, revisit the build size and inspect that use too. Changing `WidthRequest` does not edit the source artwork or its build metadata. Conversely, changing `BaseSize` does not remove empty margins inside the SVG. Tighten the drawing bounds in the source if the emblem itself looks too small within an otherwise correctly sized view.
Avoid using `Resize="false"` as a general sharpness fix. It disables vector-image resizing in this pipeline. Choose it only when that is the behavior you intend, following the [documented resize option](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/images/images#resize-an-image).
## Check a missing or unexpected image in order
1. Confirm the filename and project item. Use a lowercase name such as `compass.svg`, and check for another image with the same name. Microsoft's [naming rules](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/images/images) require unique image names and Android-compatible characters.
2. Check the view's source. For the bundled SVG workflow, use `compass.png` in XAML or C#.
3. Compare the intended display area with the baseline size. A view-size change and a build-size change belong in different places.
4. Inspect the artwork itself. Is the ring center still open? Is the coral needle distinct? Is the emblem centered, or does invisible source whitespace push it aside?
Also inspect any image metadata that changes paint. The project-image guide documents `TintColor` and `Color` for tint and background color. Leave those unset for this two-color example unless you intend to change its appearance. Check the image against the actual page background, where a lost transparent opening is easier to spot.
## When you need SVG behavior at runtime
Downloaded SVG content, interactive paths, or runtime edits need a separate implementation decision. The bundled-image instructions above do not establish support for those jobs.
For example, the [Vapolia SVG sample project](https://github.com/vapolia/Svg-Samples) documents its own `SvgImage` and `SvgImageSource` controls and embedded-resource setup. That is a different loading contract. Evaluate the renderer's supported features and target platforms using your actual file before introducing it; swapping the filename extension in a normal `Image` declaration does not install a renderer.
The same artwork also needs different setup in [Flutter's SVG image workflow](https://perfectvector.com/blog/flutter-svg-images), [SwiftUI's asset catalog](https://perfectvector.com/blog/svg-in-swiftui), and an [Android VectorDrawable import](https://perfectvector.com/blog/convert-png-to-android-vector-drawable). Reuse the source master, then follow each destination's rules.
## Prepare a vector master when only a PNG remains
If the compass or logo exists only as a PNG, PerfectVector can help create editable SVG artwork before you add it to the MAUI project. [Convert the PNG to SVG](https://perfectvector.com/convert-png-to-svg), then inspect the ring opening, small detached pieces, and spacing in an editor. Keep a clean master for later size or color changes.
Vectorization does not repair a `MauiImage` declaration or turn the bundled-image pipeline into a runtime SVG parser. If the source is already an editable SVG, work on the project configuration or drawing directly. Photos and textured artwork may be more useful as raster images; tracing them solely because the app accepts SVG sources adds a separate artwork decision.
## FAQ
**Why do I reference a PNG when I added an SVG?**
.NET MAUI converts bundled SVG image sources to PNG during the build. Keep the SVG in the project and reference the PNG filename from XAML or C#.
**Does BaseSize set the size of the Image control?**
BaseSize sets the baseline dimensions used to derive density-specific build images. The view's layout and size requests control its display area.
**Should I add another MauiImage Include to change BaseSize?**
Check whether the file is already included, including through a wildcard. Use Update to change metadata on an existing item; use Include only when the item needs to be added.
**Will this load an SVG downloaded after the app was built?**
The bundled-image workflow does not cover downloading and parsing SVG at runtime. Choose and test a runtime rendering approach for that requirement.
## Sources
1. [Microsoft — Add images to a .NET MAUI app project](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/images/images) — SVG-to-PNG processing, image items, filenames, base size, and build metadata.
2. [Microsoft — Image](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/image) — Local image references, target-density selection, view sizing, and scaling behavior.
3. [Microsoft — Item element (MSBuild)](https://learn.microsoft.com/en-us/visualstudio/msbuild/item-element-msbuild) — The difference between adding an item with Include and changing existing metadata with Update.
4. [Vapolia — SVG samples](https://github.com/vapolia/Svg-Samples) — A separate runtime SVG control and resource-loading workflow.
***
Working from a raster-only app emblem? [Turn your PNG into an editable SVG](https://perfectvector.com/convert-png-to-svg), check its openings and spacing, then add that master to MAUI and inspect the generated image in your target app.
## Explore
- [Read the HTML article](https://perfectvector.com/blog/svg-in-dotnet-maui)
- [fpdf2 SVG Images: Keep Paths in Your Python PDF](https://perfectvector.com/blog/fpdf2-svg-image.md)
- [Inkscape Command Line Export: Page, Drawing, or Object](https://perfectvector.com/blog/inkscape-cli-export.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)