Images and Fonts

Analogy categoryAnalogies

Adding Images with the Resizetizer

MAUI's build-time Resizetizer tool automatically generates the platform-specific image assets — @1x/@2x/@3x PNGs for iOS, mipmap densities (mdpi through xxxhdpi) for Android — from a single source image placed in Resources/Images and referenced in the .csproj via an MauiImage build item (usually via the default wildcard 'Resources\Images\*'), so a developer supplies one high-resolution source, often an SVG, and never hand-exports per-density bitmaps.

🏏

Cricket analogy: The Resizetizer generating multiple densities from one source is like a broadcaster producing a single master camera feed that's automatically downscaled into standard-definition and 4K streams for different viewers, without filming each resolution separately.

Image Formats, Scaling, and Aspect

The Image control's Source can point to a local resource file name, an ImageSource.FromUri for remote images, or ImageSource.FromStream for in-memory bitmap data, while Aspect controls how the image fills its bounds: AspectFit (letterboxed, preserves full image), AspectFill (crops to fill, may clip edges), or Fill (stretches to exact bounds, ignoring aspect ratio), and setting a fixed WidthRequest/HeightRequest alongside Aspect gives predictable layout even before the image finishes downloading.

🏏

Cricket analogy: AspectFill cropping an image to fill its bounds is like a TV broadcast cropping a wide-angle stadium shot to fit a vertical mobile highlights clip, losing some of the boundary rope on the edges to fill the frame.

csharp

// MauiProgram.cs
public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            fonts.AddFont("OpenSans-Bold.ttf", "OpenSansBold");
        });

    return builder.Build();
}

Embedding and Using Custom Fonts

Custom fonts are added by placing .ttf or .otf files in Resources/Fonts and registering them in MauiProgram.cs via the ConfigureFonts fluent builder call, mapping a physical font family name to an alias — for example fonts.AddFont('OpenSans-Regular.ttf', 'OpenSansRegular') — after which any Label or Button can reference FontFamily='OpenSansRegular' and, since MAUI compiles these registrations into platform-native font resources at build time, misspelling the alias produces a silent fallback to the system default font rather than a build error.

🏏

Cricket analogy: Registering a font alias like 'OpenSansRegular' in ConfigureFonts is like assigning a jersey number to a cricketer — the alias is what the scoreboard displays, mapping cleanly back to the full registered name in the team sheet.

Bold and italic variants usually need their own registered font files (e.g., OpenSans-Bold.ttf, OpenSans-Italic.ttf) rather than relying on FontAttributes='Bold' with only a regular-weight font registered — synthetic bolding/italicizing is inconsistent across iOS, Android, and Windows and often produces a font that doesn't match the family's real bold design.

The Resizetizer generates per-platform image densities from one source at build time
MauiImage build items (wildcard on Resources/Images) drive asset generation
Image.Aspect (AspectFit/AspectFill/Fill) controls how an image fills its bounds
ImageSource supports local files, FromUri for remote, and FromStream for in-memory data
Custom fonts go in Resources/Fonts and are registered via ConfigureFonts
Font files map to a short alias used in FontFamily throughout the app
Misspelled font aliases silently fall back to the system default font