Svg maui

Vapolia.Svg — SVG Component for MAUI, Android & iOS

NuGet: Vapolia.Svg (latest: 1.0.5+)
Supports: Android 23+, iOS 14.2+, Windows 10.0.19041.0+, MAUI cross-platform

---

1. MAUI Setup

MauiProgram.cs

builder
    .UseMauiApp<App>()
    .UseEasySvg();          // required — add this line
    // .UseEasySvg("eyJhbGc...") // optional license token for production

.csproj — embed SVG files

Create a folder named VectorImages/ (NOT Resources/Images/), place .svg files there, then add:

<ItemGroup>
  <None Remove="VectorImages\**\*.svg" />
  <EmbeddedResource Include="VectorImages\**\*.svg" />
</ItemGroup>

Any folder name works (images/, Icons/, etc.) — just keep it out of Resources/Images.

XAML namespace

xmlns:svg="https://vapolia.eu/svg"

---

2. Controls

SvgImage — standalone SVG display

<!-- Basic -->
<svg:SvgImage Source="logo.svg" HeightRequest="70" HorizontalOptions="Center" />

<!-- With color mapping -->
<svg:SvgImage Source="logo.svg" HeightRequest="70"
              ColorMapping="ffffff=>00ff00,000000=>0000FF" />

<!-- Remote URL -->
<svg:SvgImage WidthRequest="100"
              Source="https://example.com/image.svg" />

<!-- Inline base64 -->
<svg:SvgImage WidthRequest="100"
              Source="data:image/svg+xml;base64,PD94bWwgdmVyc2lvb..." />

<!-- Bindable color mapping with selected state -->
<svg:SvgImage Source="logo.svg" HeightRequest="60">
    <svg:ColorMapping OldColor="#000" NewColor="{Binding CurrentColor}" />
    <svg:SvgImage.ColorMappingSelected>
        <svg:ColorMapping OldColor="#000" NewColor="{Binding CurrentColor}" />
    </svg:SvgImage.ColorMappingSelected>
</svg:SvgImage>

<!-- With tap command -->
<svg:SvgImage Source="icon.svg" HeightRequest="44"
              Command="{Binding TapCommand}"
              BackgroundColor="Transparent" />

SvgImage Key Properties

Property	Type	Notes
Source	string	Filename, URL, base64, or inline SVG
HeightRequest / WidthRequest	double	Aspect ratio preserved if only one set
ColorMapping	string or list	Normal state color replacement
ColorMappingSelected	string or list	Applied when IsSelected="True"
ColorMappingDisabled	string or list	Applied when control disabled
IsSelected	bool	Toggle selected appearance
Aspect	SvgAspect	Fit (default), Fill, FitCrop
Command / CommandParameter	ICommand / object	Tap handler for MVVM
BackgroundColor	Color	Required for tap/command on some platforms
IsLoadAsync	bool	Default: true

SvgImageSource — for Button icons, Tab icons, NavigationBar

Width and/or Height are mandatory (MAUI limitation: ImageSource is static).

<!-- Button with SVG icon -->
<Button Text="Add Contact"
        ContentLayout="Right,20"
        ImageSource="{svg:Svg tabHome.svg,Height=60,ColorMapping='000000=>FF0000'}" />

<!-- TabbedPage / Shell tab icon -->
<NavigationPage Title="Home" IconImageSource="{svg:Svg tabHome.svg,Height=60}">
    <x:Arguments><views:HomePage /></x:Arguments>
</NavigationPage>

<!-- Page icon -->
<ContentPage IconImageSource="{svg:Svg myicon.svg,Height=60}" ...>

<!-- Standard MAUI Image control -->
<Image Source="{svg:Svg no_image_available.svg, Width=40, ColorMapping='000=>666'}"
       WidthRequest="40" />

Note: SvgImageSource renders to a raster image — supports only one ColorMapping, no selected/disabled states.

---

3. Source Schemes

Prefix	Meaning	Example
(none) or res:	Embedded resource	logo.svg or res:MyApp.Images.logo.svg
file:	Native bundled resource	file:logo.svg
nfile:	Device file system	nfile:/data/user/0/com.app/files/img.svg
string:	Inline SVG content	string:<svg xmlns="...">...</svg>
http: / https:	Remote URL	https://example.com/image.svg

---

4. Color Mapping Syntax

Format: oldColor=>newColor — multiple mappings separated by ,, ;, or space.
Color formats: AARRGGBB, RRGGBB, RGB (hex, no # needed in string form).

"000=>FF0000"                       → black to red
"ffffff=>00ff00,000000=>0000FF"     → white→green AND black→blue
"FFF=>666"                          → white→gray
"000000=>e01a1a"                    → black→dark red

Bindable form using ColorMapping objects:

<svg:SvgImage Source="icon.svg" HeightRequest="32">
    <svg:ColorMapping OldColor="Blue" NewColor="#80000000" />
    <svg:ColorMapping OldColor="#FFF" NewColor="{Binding AccentColor}" />
</svg:SvgImage>

Resource dictionary reuse:

<svg:ColorMappings x:Key="ButtonIconColors">
    <svg:ColorMapping OldColor="#000" NewColor="{StaticResource PrimaryColor}" />
</svg:ColorMappings>

<svg:SvgImage Source="icon.svg" ColorMapping="{StaticResource ButtonIconColors}" />

---

5. Native Android (without MAUI)

MainActivity.cs

Vapolia.Svgs.Config.AddResourceAssembly(typeof(MainActivity));

Layout XML

<vapolia.SvgImageView
    app:svg="car.svg"
    app:colorMapping="000000=>FF0000"
    app:colorMappingSelected="000000=>FF3030"
    app:colorMappingDisabled="000000=>1A1A1A"
    app:aspect="fit"
    android:layout_width="200dp"
    android:layout_height="wrap_content" />

Programmatic (toolbar/navigation icon)

var toolbar = FindViewById<Toolbar>(Resource.Id.toolbar);
toolbar.NavigationIcon = SvgFactory.GetDrawable("backward.svg", "000000=>FFFFFF");

---

6. Native iOS (without MAUI)

AppDelegate.cs

using Vapolia.Svgs;
var svg = await SvgFactory.FromUri(SvgSource.FromNativeFile("info.svg"));

Xcode Interface Builder (User Defined Runtime Attributes on UISvgImageView)

Key Path	Type	Example
BundleName	String	info.svg
ColorMapping	String	000000=>FF0000
ColorMappingSelected	String	000000=>0000FF
Aspect	String	Fit, Fill, FitCrop
IsLoadAsync	Boolean	YES

---

7. Windows limitations

• ColorMappings not supported on Windows
• Command requires a non-transparent BackgroundColor
• Async loading always enabled

---

8. Bindings & limitations

⚠️ The {svg:Svg ...} markup extension does NOT support bindings on its parameters (Height, Width, ColorMapping). The XAML SourceGen cannot convert a Binding to the CLR types (Vapolia.Svgs.ColorMapping, double, etc.) the markup expects. Typical error:

CS0030: Cannot convert type 'Microsoft.Maui.Controls.BindingBase' to 'Vapolia.Svgs.ColorMapping'

Rule: use the markup extension only with literal/static values:

ImageSource="{svg:Svg icon.svg,Height=20,ColorMapping='000000=>FFFFFF'}"

When dynamic binding is required: use the <svg:SvgImage> control directly — its properties are BindableProperty and accept all binding forms:

<svg:SvgImage Source="icon.svg" WidthRequest="18"
              ColorMapping="{Binding TextColor, Converter={StaticResource ColorToBlackColorMappingStringConverter}}" />

For a button with a dynamic icon, compose a Border + TapGestureRecognizer + HorizontalStackLayout containing SvgImage + Label, rather than using Button.ImageSource.

---

9. Common Mistakes & Troubleshooting

Symptom	Cause	Fix
Nothing displays	SVG not set as EmbeddedResource	Check .csproj <EmbeddedResource Include="...">
Nothing displays	SVG missing viewBox attribute	Open SVG in text editor, add viewBox="0 0 W H" to <svg> tag
Nothing displays	SVG color = background color	Use ColorMapping or edit SVG
SVG not found	Assembly Name ≠ Default Namespace	Use full resource name: YourNamespace.Folder.file.svg
Nothing displays	UseEasySvg() missing	Add to MauiProgram.cs
Button ImageSource broken	Set in Style/Trigger	Set on Image property, not ImageSource in styles
Color binding not working	Using SvgImageSource	Use SvgImage instead — SvgImageSource is raster-only

Discover full embedded resource names at runtime:

var names = GetType().Assembly.GetManifestResourceNames()
    .Where(r => r.EndsWith(".svg"));

---

10. Full MAUI Page Example

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:svg="https://vapolia.eu/svg"
             x:Class="MyApp.MainPage"
             IconImageSource="{svg:Svg appicon.svg,Height=60}">
    <VerticalStackLayout Padding="16" Spacing="12">

        <svg:SvgImage Source="logo.svg" HeightRequest="80" HorizontalOptions="Center" />

        <svg:SvgImage Source="logo.svg" HeightRequest="50"
                      ColorMapping="000=>e01a1a" />

        <Button Text="Next" ImageSource="{svg:Svg arrow.svg,Height=20}"
                ContentLayout="Right,5"
                Command="{Binding NextCommand}" />

    </VerticalStackLayout>
</ContentPage>