🚀 Introducing Papiro: A Free, Native HTML-to-PDF Library for .NET MAUI

Developing mobile apps often requires generating PDF reports—invoices, service orders, receipts, or custom documents. The problem? Existing solutions tend to be complex, expensive, or overly heavy for simple needs.

That's why I created Papiro, a free and fully native library for converting HTML to PDF in .NET MAUI applications, without external dependencies, embedded browsers, or expensive commercial licenses.

Papiro Logo

😩 The Problem with Current Solutions

If you've ever tried generating PDFs in mobile apps, you've probably encountered one of these scenarios:

Expensive commercial libraries: Tools like iText or Syncfusion require licenses that can cost thousands of dollars annually.
Tedious low-level APIs: Drawing each PDF element manually (drawing lines, calculating x/y coordinates) is laborious and makes styling a nightmare.
Browser-based solutions: Embedding heavy dependencies like Chromium drastically increases your app size.
Unnecessary feature bloat: Many MAUI libraries are designed for complex enterprise scenarios when all you need is a simple report.

💡 Why HTML is the Perfect Solution

HTML is the perfect template language for reports. Every developer knows it, it's easy to style with CSS, can be previewed in any browser, and offers complete design flexibility.

Papiro bridges this gap: you write your report in HTML, use simple placeholders like {{customer_name}} for dynamic data, and generate a native PDF in seconds.

✨ Key Features

Feature	Description
🆓 100% Free	Uses native Android and iOS platform APIs. No iText, no Chromium, no Syncfusion.
⚡ Extremely Lightweight	No heavy external dependencies. The library adds less than 100KB to your app.
📄 Automatic Pagination	Automatically splits long content into multiple A4 pages.
🎨 High Visual Quality	Uses 3x scale factor to ensure crisp text and images (~220 DPI).
📱 Native Rendering	Uses the underlying platform's WebView engine for consistent rendering.
🔄 Modern Async/Await	Modern asynchronous interface with detailed result objects.
🏷️ Template System	Built-in support for `{{variable}}` tag substitution.
⏱️ Hang Protection	Built-in 30-second timeout prevents infinite rendering hangs.

📦 Quick Installation

Add the NuGet package to your .NET MAUI project:

<PackageReference Include="CwSoftware.Papiro" Version="1.0.0" />

using CwSoftware.Papiro;

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    builder
        .UseMauiApp<App>()
        .UsePapiro();  // ✅ Add this line

    return builder.Build();
}

🛠️ Practical Example: Generating an Invoice

See how simple it is to generate a PDF with dynamic data using Papiro:

using CwSoftware.Papiro;
using System.Globalization;

public class InvoiceService
{
    private readonly IHtmlToPdfService _pdfService;

    public InvoiceService(IHtmlToPdfService pdfService)
    {
        _pdfService = pdfService;
    }

    public async Task<string?> GenerateInvoiceAsync(string customer, decimal total)
    {
        // 1. Define your HTML template
        string template = @"
            <html>
            <head>
                <style>
                    body { font-family: Helvetica, Arial, sans-serif; padding: 40px; }
                    h1 { color: #2c3e50; border-bottom: 3px solid #3498db; padding-bottom: 10px; }
                    .info { margin: 20px 0; background: #f8f9fa; padding: 15px; border-radius: 5px; }
                    .total { font-size: 24px; font-weight: bold; color: #27ae60; margin-top: 30px; text-align: right; }
                    table { width: 100%; border-collapse: collapse; margin-top: 20px; }
                    th { background: #3498db; color: white; padding: 10px; text-align: left; }
                    td { border-bottom: 1px solid #ddd; padding: 10px; }
                </style>
            </head>
            <body>
                <h1>📋 Service Invoice</h1>

                <div class='info'>
                    <p><strong>Customer:</strong> {{Customer}}</p>
                    <p><strong>Date:</strong> {{Date}}</p>
                    <p><strong>Invoice ID:</strong> #{{Id}}</p>
                </div>

                <table>
                    <tr><th>Description</th><th>Amount</th></tr>
                    <tr><td>Technical Consulting</td><td>{{Total}}</td></tr>
                </table>

                <p class='total'>Total Amount: {{Total}}</p>
            </body>
            </html>";

        // 2. Replace tags with real data
        string html = HtmlTemplateHelper.ReplaceTags(template, new 
        {
            Customer = customer,
            Id = new Random().Next(1000, 9999),
            Date = DateTime.Now.ToString("MM/dd/yyyy"),
            Total = total.ToString("C2", new CultureInfo("en-US"))
        });

        // 3. Generate PDF
        var result = await _pdfService.ConvertAndSaveAsync(html, "invoice.pdf");

        if (result.IsSuccess)
        {
            // Open generated PDF using the native launcher
            await Launcher.Default.OpenAsync(new OpenFileRequest
            {
                Title = "Invoice",
                File = new ReadOnlyFile(result.FilePath!)
            });
            return result.FilePath;
        }

        Console.WriteLine($"Error: {result.ErrorMessage}");
        return null;
    }
}

🖼️ Handling Images & Logos

Using local images in HTML-to-PDF generation can be tricky due to file access restrictions on mobile devices. Papiro makes this easy by providing helpers to convert images to Base64 strings, which can be embedded directly into your HTML.

// From a local file
string logoBase64 = await HtmlTemplateHelper.ImageToBase64Async("/storage/emulated/0/logo.png");

// From an embedded resource in your app
string logoBase64 = await HtmlTemplateHelper.EmbeddedResourceToBase64Async("MyProject.Resources.Images.logo.png");

// Use it in your HTML
string template = @"<img src='{{LogoBase64}}' alt='Logo' width='150' />";
string html = HtmlTemplateHelper.ReplaceTags(template, new { LogoBase64 = logoBase64 });

📱 Platform Support

Android: API 21+ (Lollipop). Uses PdfDocument and manual Canvas pagination.
iOS: iOS 11+. Uses UIMarkupTextPrintFormatter and UIPrintPageRenderer.

📂 Conclusion

Generating PDFs in mobile apps doesn't need to be expensive or complicated. Papiro offers a simple, native, and free solution that leverages HTML—a technology every developer already knows—to create professional documents in seconds.

If you are building commercial apps with .NET MAUI and need reports, invoices, or receipts, give Papiro a try.

🔗 Links

GitHub Repository: CW-Software-Apps/Papiro-MAUI-HtmlToPDF
NuGet Package: CwSoftware.Papiro
Sample App: View Samples

If you found this library useful, please give it a star ⭐ on GitHub!

Papiro: A Free, Native HTML-to-PDF Library for .NET MAUI