Work with SVG Fonts and Text in C#

Text rendering is one of the most sensitive parts of SVG processing. The same SVG document can produce different visual results depending on font availability, operating system, or rendering environment. This often leads to situations where SVG text looks correct in a browser but renders differently when converted on a server.

Aspose.SVG for .NET provides a complete API for working with SVG text, including creating text elements, applying custom fonts, handling font fallback, and defining font faces in SVG documents. This makes it possible to generate predictable and platform-independent output when converting SVG to images or PDF.

In this article, you will learn how to:

• Create and style SVG text elements programmatically
• Use custom fonts through Configuration and FontsSettings
• Understand and control font fallback behavior during rendering
• Define fonts in SVG using @font-face

All examples use Aspose.SVG for .NET and focus on real-world server-side scenarios, such as SVG to image or SVG to PDF conversion, where system fonts cannot be reliably assumed.

Understanding How Fonts Work in SVG

Unlike HTML, SVG handles text and fonts in a more explicit and declarative way. Fonts in SVG are not automatically resolved based on the browser or operating system alone — instead, they follow a well-defined lookup and fallback process defined by the SVG and CSS specifications.

Understanding this process is essential before working with custom fonts, @font-face, or SVG-to-PDF conversion.

Font Resolution in SVG

When an SVG document contains text, two related steps affect the final result. First, the SVG and CSS cascade determines the effective font-family value for each text element. Then the rendering engine resolves that family name to an available font face.

The effective font-family can be set by:

1. Explicit font declarations – Fonts defined directly on elements using:

   • font-family attributes
   • inline style attributes
   • CSS rules inside <style>

2. Inherited or global SVG styles – CSS rules and inherited text properties that apply when no more specific value overrides them.

After the final font-family value is known, the renderer searches for a matching font in sources such as:

1. Embedded fonts – Font faces defined via @font-face inside the SVG document.

2. Configured or system font sources – Fonts provided by the rendering engine, such as:

   • custom font folders configured via API
   • system-installed fonts

3. Generic fallback fonts – If no matching font is found, a generic family such as sans-serif or serif is used.

Refer to the article SVG Styles: CSS vs Inline vs Attributes to learn more about CSS rules, inline styles, and presentation attributes.

SVG Is Not HTML

SVG uses CSS syntax, but its font handling differs from HTML:

• SVG does not inherit fonts from the surrounding document when rendered or converted.
• Inline attributes and <tspan> styles have higher priority than global CSS rules.
• Fonts must be fully resolved at rendering or conversion time.

These differences explain why SVG text often behaves unexpectedly when system fonts or implicit inheritance are used. As a result, SVG documents often require explicit font configuration to ensure consistent appearance.

To learn how to diagnose and fix SVG styling and font issues, see the article Common SVG Styling and Font Issues.

Why Fonts Behave Differently During Conversion

When converting SVG to formats such as PNG or PDF:

• The rendering engine must fully resolve fonts at conversion time.
• Missing fonts cannot be substituted later.
• Any ambiguity in font lookup leads to fallback fonts being used.

This is why an SVG that looks correct in one environment may render differently when converted on a server or CI system.

Key Takeaway

To work with fonts reliably in SVG:

• Always specify explicit font-family values.
• Include fallback fonts.
• Embed fonts using @font-face or provide them via configuration.
• Don’t rely on the required font being installed on the machine where the SVG will be rendered or converted.

The following sections demonstrate these principles in practice using Aspose.SVG for .NET.

Using Custom Fonts via Configuration

The most straightforward way to work with text in SVG is to create and configure <text> elements directly through the SVG DOM. This approach gives you full control over positioning and basic font properties without relying on CSS or external styles.

Below is a simple example that demonstrates how to create a text element and render SVG text using a custom font by configuring a fonts lookup directory.

using Aspose.Svg.Saving;
using Aspose.Svg.Rendering.Image;
using Aspose.Svg.Converters;
using System.IO;

// Render SVG text with a custom font using FontsSettings in C#

// Create an instance of the Configuration class
using (Configuration configuration = new Configuration())
{
    // Configure custom fonts folder
    IUserAgentService userAgentService = configuration.GetService<IUserAgentService>();

    userAgentService.FontsSettings.SetFontsLookupFolder(Path.Combine(DataDir, "fonts"));

    // Create SVG document WITH configuration
    using (SVGDocument document = new SVGDocument(configuration))
    {
        // Create <text> element
        SVGTextElement text = (SVGTextElement)document.CreateElementNS("http://www.w3.org/2000/svg", "text");

        text.SetAttribute("x", "50");
        text.SetAttribute("y", "100");
        text.SetAttribute("font-family", "Montserrat");
        text.SetAttribute("font-size", "24");
        text.TextContent = "Custom Font Example";

        document.RootElement.AppendChild(text);

        // Convert SVG to JPG
        ImageSaveOptions saveOptions = new ImageSaveOptions(ImageFormat.Jpeg);

        Converter.ConvertSVG(document, saveOptions, Path.Combine(OutputDir, "custom-font.jpg"));
    }
}

The Configuration class serves as the central container for all rendering settings. In this example, a Configuration creates an isolated processing environment into which a document is passed to ensure custom settings are applied. The IUserAgentService is used to configure the font search path using FontsSettings.SetFontsLookupFolder(), allowing the rendering engine to find and apply the specified font when converting text to an image.

For existing SVG files, configure font lookup before creating or loading the SVGDocument. Also make sure the font-family value in SVG matches the font’s internal family name, not only the .ttf or .otf file name.

Using @font-face in SVG

In many SVG scenarios, relying on system-installed fonts is not reliable. The same SVG may look different if the target system lacks a specific font. To make rendering more predictable, you can define custom fonts directly in your SVG using the @font-face rule.

This approach allows you to:

• Use fonts that are not installed on the system.
• Precisely control text rendering across all platforms.
• Define fonts from local or explicitly resolvable font files.

Below is a practical example that demonstrates how to embed a font in an SVG and render it in a PDF using Aspose.SVG for .NET.

using Aspose.Svg.Saving;
using Aspose.Svg.Converters;
using System.IO;

// Create an SVG @font-face rule programmatically and convert SVG text to PDF in C#

// Create SVG document
using (SVGDocument document = new SVGDocument())
{
    SVGSVGElement root = document.RootElement;

    // Create <style> element
    SVGStyleElement style = (SVGStyleElement)document.CreateElementNS("http://www.w3.org/2000/svg", "style");

    style.SetAttribute("type", "text/css");

    // Define @font-face rule programmatically
    style.TextContent =
        "@font-face { " +
        "  font-family: 'VeinlineRegular'; " +
        "  src: url(https://assets.ithillel.ua/wiki/VeinlineRegular.ttf); " +
        "} " +
        "text { " +
        "  font-family: 'VeinlineRegular', sans-serif; " +
        "  font-size: 28px; " +
        "  fill: #2c3e50; " +
        "}";

    // Append <style> to SVG root
    root.AppendChild(style);

    // Create <text> element
    SVGTextElement text = (SVGTextElement)document.CreateElementNS("http://www.w3.org/2000/svg", "text");
    text.SetAttribute("x", "40");
    text.SetAttribute("y", "90");
    text.TextContent = "SVG text rendered with @font-face";

    root.AppendChild(text);

    // Convert SVG to PDF
    PdfSaveOptions pdfOptions = new PdfSaveOptions();
    Converter.ConvertSVG(document, pdfOptions, Path.Combine(OutputDir, "svg-font-face-programmatically.pdf"));
}

Key Points

• @font-face defines a named font face for SVG text. For server-side conversion, prefer local font files or resources that are explicitly available in the processing environment.
• Fallback fonts are specified: 'VeinlineRegular', sans-serif ensures a fallback if the embedded font fails.
• Consistent output across platforms: Using the same font files and fallback list helps PDF and image output stay consistent across machines.
• Base URI matters: When using relative font paths in @font-face, set a base URI in the SVGDocument constructor so the paths can be resolved.

This example is particularly useful for scenarios where:

• You generate reports, invoices, or certificates in SVG and convert them to PDF.
• Your SVG must render consistently on servers with different installed fonts.
• You need to embed corporate or licensed fonts directly into the SVG.

Font Lookup and Fallback Behavior

When rendering SVG text, Aspose.SVG for .NET uses a font search mechanism to locate the specified font. If the requested font is not available on the system or in the custom font folders, a fallback font is automatically applied. Understanding this behavior is crucial to avoid unexpected rendering results, such as Arial being displayed instead of the desired font.

Why SVG Fonts Fall Back to Arial or Default Fonts

SVG supports font family lists, just like CSS:

font-family: 'Montserrat', 'Arial', sans-serif;

The renderer evaluates each font from left to right and selects the first available font. This makes fallback lists a critical part of predictable SVG rendering. If no fallback is specified, the renderer applies a default font, which may vary depending on the platform or rendering engine.

The following example demonstrates how custom fonts are prioritized and what happens when a font is missing.

using Aspose.Svg.Saving;
using Aspose.Svg.Converters;
using System.IO;

// Convert SVG text to PNG with custom font fallback in C#

// Create configuration and specify custom fonts directory
using (Configuration configuration = new Configuration())
{
    IUserAgentService userAgentService = configuration.GetService<IUserAgentService>();
    userAgentService.FontsSettings.SetFontsLookupFolder(Path.Combine(DataDir, "fonts"));

    // Load existing SVG document
    using (SVGDocument document = new SVGDocument(Path.Combine(DataDir, "input.svg"), configuration))
    {
        // Find the first <text> element in the document
        SVGTextElement text = document.QuerySelector("text") as SVGTextElement;

        if (text != null)
        {
            // Set custom font with fallback
            text.SetAttribute("font-family", "'Montserrat', sans-serif");
        }
        document.Save(Path.Combine(OutputDir, "font-fallback.svg"));

        // Convert SVG to PNG
        ImageSaveOptions saveOptions = new ImageSaveOptions();
        Converter.ConvertSVG(document, saveOptions, Path.Combine(OutputDir, "font-fallback.png"));
    }
}

Production Tips

• Custom fonts folder: SetFontsLookupFolder allows you to prioritize your own fonts before system fonts.
• Automatic fallback: If the requested font does not exist, Aspose.SVG will automatically use a fallback font (often Arial or the default sans-serif).
• Consistent results: To ensure predictable rendering, always provide your custom fonts or use @font-face embedding.
• Font lookup order: Custom fonts → system-installed fonts → generic fallback.

This example helps developers understand why sometimes SVG text may not render in the expected font and how to control fallback behavior by properly configuring font lookup.

Note: When saving an SVG document, Aspose.SVG preserves font-family declarations but does not automatically embed or resolve font files. Font lookup folders are used only during rendering or conversion. To make a custom font work within the SVG, it must be defined with @font-face.

Ensuring Consistent Text Rendering During SVG Conversion

Rendering SVG text consistently across different platforms can be challenging. Differences in system-installed fonts, missing fonts, or conflicting inline styles can lead to unexpected results when converting SVG to images or PDF.

Aspose.SVG for .NET allows you to control font lookup, embed fonts, and normalize text styles, ensuring that your output is consistent regardless of the environment.

using Aspose.Svg.Rendering;
using Aspose.Svg.Rendering.Image;
using Aspose.Svg.Rendering.Pdf;
using System.IO;

// Ensure consistent SVG text rendering in PNG and PDF using custom fonts in C#

// Create configuration to specify custom fonts folder
using (Configuration configuration = new Configuration())
{
    IUserAgentService userAgentService = configuration.GetService<IUserAgentService>();

    // Set folder containing your custom fonts
    userAgentService.FontsSettings.SetFontsLookupFolder(Path.Combine(DataDir, "fonts"));

    // Create SVG document with configuration
    using (SVGDocument document = new SVGDocument(configuration))
    {
        // Create <text> element
        SVGTextElement text = (SVGTextElement)document.CreateElementNS("http://www.w3.org/2000/svg", "text");

        text.SetAttribute("x", "50");
        text.SetAttribute("y", "100");
        text.SetAttribute("font-family", "'Montserrat', sans-serif"); // custom font with fallback
        text.SetAttribute("font-size", "36");
        text.SetAttribute("fill", "#2c3e50");
        text.TextContent = "Consistent Rendering Example";

        document.RootElement.AppendChild(text);

        // Initialize an instance of the ImageDevice class and specify an output file to render
        IDevice device1 = new ImageDevice(new ImageRenderingOptions(), Path.Combine(OutputDir, "consistent-text.png"));

        // Render SVG to PNG
        document.RenderTo(device1);

        // Initialize an instance of the PdfDevice class and specify an output file to render
        IDevice device2 = new PdfDevice(new PdfRenderingOptions(), Path.Combine(OutputDir, "consistent-text.pdf"));

        // Render SVG to PDF
        document.RenderTo(device2);
    }
}

Rendering Notes

• Configuration ensures predictable font lookup: All text elements use the specified custom fonts before falling back to system fonts.
• Consistent rendering across formats: The same SVG can render consistently in PNG and PDF outputs when both conversions use the same font configuration.
• Font fallback safety: Including a fallback font ensures text remains readable if the primary font is unavailable.
• Inline style conflicts are avoided: Use normalized attributes or <style> to control font consistently.

This approach is essential for production scenarios, such as generating reports, certificates, or automated documents, where SVG text must stay visually consistent across machines.

Quick Font Handling Recipes

Goal	Recommended Approach	Notes
Render SVG text consistently on any server	Embed fonts using @font-face	Makes SVG less dependent on system-installed fonts
Avoid unexpected Arial or default font fallback	Specify a font-family list with a generic fallback	Example: 'CustomFont', sans-serif
Use custom fonts during SVG to image or PDF conversion	Configure FontsSettings via Configuration	Font lookup folders are applied only at render time
Keep SVG portable across environments	Prefer @font-face over server-side font lookup	Font resources are declared in the SVG instead of assumed from the system
Ensure consistent text metrics after conversion	Use the same font source for all outputs	Prevents layout shifts caused by fallback fonts
Load fonts from relative paths in @font-face	Set a base URI when creating SVGDocument	Required for resolving relative font URLs

Troubleshooting Font Issues

If text still renders with an unexpected font, the cause is usually one of three things: the font was not available to the renderer, the font-family value does not match the font’s internal family name, or inline styles on <text> or <tspan> elements override the rule you expected to apply.

For a step-by-step diagnostic guide, including browser-vs-conversion differences, Arial/default fallback, inline style conflicts, and relative resource paths, see Common SVG Styling and Font Issues.

Related Resources

• Edit SVG File – You will learn how to edit SVG using Aspose.SVG for .NET library. Detailed examples of adding and editing new elements in SVG and applying SVG filters to bitmaps are considered.
• Environment Configuration – You will learn how to create various configurations and adapt them to the different environments where the application runs. This can be a custom theme, a runtime service or a web request network service.
• Rule Builder – You will learn about the Rule Builder styling feature, which enables developers to apply CSS-like rules to SVG elements.
• SVG Styles: CSS vs Inline vs Attributes – Learn how SVG styles work, compare CSS rules, inline styles, and presentation attributes, and understand styling priority when working with SVG.
• Common SVG Styling and Font Issues – Learn how to diagnose and fix SVG styling and font issues, including CSS priority conflicts, font fallback problems, and inconsistent rendering when converting SVG.
• Modify SVG Styles Programmatically in C# – Learn how to programmatically modify SVG styles in C# using Aspose.SVG.
• Convert SVG to PDF in C# – Learn how to convert SVG documents to PDF using Aspose.SVG for .NET.
• Convert SVG to Image – Learn how to convert SVG to PNG, JPG, BMP, TIFF, and GIF in C#.
• Text Vectorization & Text Security – Learn how to convert SVG text to vector paths when exact appearance must be preserved without font dependencies.