DEV Community

IronSoftware
IronSoftware

Posted on

PDF Viewer in .NET MAUI (C# .NET 10 Guide)

#csharp #dotnet

PDF viewing in applications enables users to read contracts, view invoices, review documentation, and examine reports without leaving your app or switching to external PDF readers. I've built document management systems, legal review applications, and invoice approval workflows where embedded PDF viewing transformed user experience — users annotate contracts inline, approve invoices with context visible, and review technical documentation without context-switching between applications.

The challenge is that traditional PDF viewing solutions require platform-specific implementations. Windows Forms uses WebBrowser controls or third-party ActiveX components. WPF requires different approaches. Web applications use iframe embeds or JavaScript libraries like PDF.js. Building cross-platform applications meant maintaining separate PDF viewing code for each target platform — Windows desktop, macOS, web, mobile.

.NET MAUI (Multi-platform App UI) promises single codebase, multiple platforms, but PDF viewing wasn't built-in. Third-party libraries existed but came with limitations. Free options like Spire.PDFViewer restrict viewing to 10 pages — useless for real documents. Commercial solutions like Syncfusion or DevExpress require complex licensing. Stack Overflow threads from 2022-2023 recommend platform-specific workarounds or embedding web views with PDF.js — functional but fragile across iOS, Android, Windows, and macOS.

IronPDF's MAUI viewer (IronPdf.Viewer.Maui) provides a single control working across MAUI-supported platforms. Add the NuGet package, configure in MauiProgram.cs, add <IronPdfView> to your XAML, set the Source property. The viewer handles rendering, zoom, navigation, printing — consistent API regardless of target platform.

Understanding cross-platform PDF rendering complexity explains why most solutions fail. PDFs aren't simple images — they contain vector graphics, embedded fonts, form fields, annotations, JavaScript, encryption. Rendering accurately requires implementing the full PDF specification (ISO 32000). Platform-specific viewers (Preview on macOS, Adobe on Windows) invest millions in implementation. Cross-platform libraries must either bundle rendering engines (large binary sizes) or use platform APIs (inconsistent results).

using IronPdf.Viewer.Maui;

// In your MAUI ContentPage
public class PdfViewerPage : ContentPage
{
    public PdfViewerPage()
    {
        var pdfView = new IronPdfView
        {
            Source = IronPdfViewSource.FromFile("contract.pdf"),
            Options = IronPdfViewOptions.All
        };

        Content = pdfView;
    }
}
Enter fullscreen mode Exit fullscreen mode

This creates a full-featured PDF viewer with toolbar, zoom controls, page navigation, and print functionality. The Options = IronPdfViewOptions.All shows all viewer features. Customize by selecting specific options or hiding the toolbar entirely with IronPdfViewOptions.None.

How Do I Install the IronPDF MAUI Viewer?

Install IronPdf.Viewer.Maui via NuGet Package Manager Console:

Install-Package IronPdf.Viewer.Maui
Enter fullscreen mode Exit fullscreen mode

Or via .NET CLI:

dotnet add package IronPdf.Viewer.Maui
Enter fullscreen mode Exit fullscreen mode

After installation, configure the viewer in MauiProgram.cs:

using IronPdf.Viewer.Maui;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureIronPdfView(); // Initialize viewer

        return builder.Build();
    }
}
Enter fullscreen mode Exit fullscreen mode

The ConfigureIronPdfView() method registers required services and handlers for the PDF viewer control. Without this initialization, the IronPdfView control won't render.

For licensed usage (removes trial [watermarks](https://ironsoftware.com/csharp/barcode/how-to/create-barcode-images/)), pass your license key:

.ConfigureIronPdfView("YOUR-LICENSE-KEY")
Enter fullscreen mode Exit fullscreen mode

This one-time setup enables PDF viewing throughout your MAUI application.

How Do I Create a PDF Viewer Page?

Create a ContentPage with IronPdfView using XAML or C#. XAML approach:

<?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:ipv="clr-namespace:IronPdf.Viewer.Maui;assembly=IronPdf.Viewer.Maui"
             x:Class="MyApp.PdfViewerPage">

    <ipv:IronPdfView x:Name="pdfView"
                     Source="documents/manual.pdf"
                     Options="All" />
</ContentPage>
Enter fullscreen mode Exit fullscreen mode

The xmlns:ipv namespace import makes IronPdfView available in XAML. Set Source to a file path relative to your app resources or absolute path. The Options attribute controls toolbar visibility.

C# code-behind approach:

using IronPdf.Viewer.Maui;

public class PdfViewerPage : ContentPage
{
    private readonly IronPdfView pdfView;

    public PdfViewerPage()
    {
        pdfView = new IronPdfView
        {
            Options = IronPdfViewOptions.All
        };

        Content = pdfView;

        // Load PDF after page loads
        Loaded += async (s, e) =>
        {
            pdfView.Source = IronPdfViewSource.FromFile("report.pdf");
        };
    }
}
Enter fullscreen mode Exit fullscreen mode

This creates the viewer programmatically. The Loaded event handler ensures the page is fully initialized before loading the PDF, preventing timing issues on slower devices.

I use the C# approach when PDF sources are dynamic — loaded from databases, downloaded from APIs, or selected by users. XAML works well for static PDF documentation or help files bundled with the app.

What Are the Different Ways to Load PDFs?

IronPdfView supports three loading methods:

From file path:

pdfView.Source = IronPdfViewSource.FromFile("/path/to/document.pdf");
Enter fullscreen mode Exit fullscreen mode

Use for PDFs stored in app resources, downloaded to device storage, or accessible via file system paths.

From byte array:

byte[] pdfBytes = await DownloadPdfAsync();
pdfView.Source = IronPdfViewSource.FromBytes(pdfBytes);
Enter fullscreen mode Exit fullscreen mode

Use for PDFs fetched from APIs, databases, or generated in-memory. I fetch PDFs from REST APIs returning byte arrays and display them without saving to disk — useful for sensitive documents that shouldn't persist locally.

From stream:

using var stream = File.OpenRead("document.pdf");
pdfView.Source = IronPdfViewSource.FromStream(stream);
Enter fullscreen mode Exit fullscreen mode

Use when working with existing file streams, network streams, or memory streams. Streaming is efficient for large PDFs — rendering begins before the entire file loads.

For user-selected files (file picker scenarios):

var result = await FilePicker.PickAsync(new PickOptions
{
    FileTypes = new FilePickerFileType(new Dictionary<DevicePlatform, IEnumerable<string>>
    {
        { DevicePlatform.iOS, new[] { "public.pdf" } },
        { DevicePlatform.Android, new[] { "application/pdf" } },
        { DevicePlatform.WinUI, new[] { ".pdf" } },
        { DevicePlatform.macOS, new[] { "pdf" } }
    })
});

if (result != null)
{
    using var stream = await result.OpenReadAsync();
    pdfView.Source = IronPdfViewSource.FromStream(stream);
}
Enter fullscreen mode Exit fullscreen mode

This opens a platform-native file picker restricted to PDF files, then loads the selected PDF into the viewer.

How Do I Customize the Viewer Toolbar?

The Options property controls which features appear in the toolbar:

Show all features:

pdfView.Options = IronPdfViewOptions.All;
Enter fullscreen mode Exit fullscreen mode

This displays thumbnails, open file, print, zoom, and navigation controls.

Hide toolbar completely:

pdfView.Options = IronPdfViewOptions.None;
Enter fullscreen mode Exit fullscreen mode

Use for read-only viewing where you control navigation programmatically or want minimal UI.

Show specific features:

pdfView.Options = IronPdfViewOptions.Thumbs | IronPdfViewOptions.Open;
Enter fullscreen mode Exit fullscreen mode

This shows only thumbnail navigation and file open button. Combine options using bitwise OR (|) to create custom toolbars.

Available options:

  • Thumbs: Thumbnail page preview panel
  • Open: File open dialog button
  • Print: Print PDF button
  • Zoom: Zoom in/out controls
  • Navigation: Page forward/backward buttons

I customize toolbars based on context. Legal document review apps show all options — users need full control. Invoice approval workflows hide Open and Print — users should only view the specific invoice loaded programmatically, not open arbitrary files or print without approval workflow completion.

Does This Work on All Platforms?

IronPDF MAUI viewer currently supports Windows and macOS desktop applications. iOS and Android support is under development. If your MAUI project targets mobile platforms, untarget them in the .csproj file:

<TargetFrameworks>net10.0-windows;net10.0-macos</TargetFrameworks>
Enter fullscreen mode Exit fullscreen mode

Remove net10.0-android and net10.0-ios if present. The viewer will work on desktop platforms while mobile support is added.

For web-based PDF viewing (Blazor WebAssembly or Blazor Server), use different approaches:

<!-- Browser native PDF rendering -->
<iframe src="/documents/report.pdf" width="100%" height="800px"></iframe>
Enter fullscreen mode Exit fullscreen mode

Or integrate Mozilla's PDF.js library for more control over rendering and UI.

I've deployed MAUI desktop applications to enterprise environments where users needed PDF viewing on Windows and macOS workstations. The single codebase compiled to both platforms without platform-specific PDF viewing code.

How Does IronPDF Compare to Other MAUI PDF Solutions?

Spire.PDFViewer (Free Version):

  • Limitation: 10-page maximum
  • Impact: Unusable for real documents (contracts, manuals, reports)
  • Licensing: Free version severely restricted, paid version required for production

Syncfusion PDF Viewer:

  • Complexity: Requires Syncfusion account, complex licensing
  • Overhead: Large dependency, adds significant app size
  • Cost: Commercial license required, per-developer pricing

Custom WebView + PDF.js:

  • Fragility: Different behavior across platforms (iOS WebView vs Android WebView vs Windows WebView2)
  • Maintenance: Managing PDF.js versions, handling security updates
  • Limited: No native printing, limited zoom control, JavaScript required

Platform-Specific Viewers (WebBrowser, Preview):

  • Platform Lock-In: Separate code for Windows, macOS, mobile
  • Inconsistency: Different features available per platform
  • Complexity: Conditional compilation, platform-specific testing

IronPDF provides consistent API, works across desktop platforms, handles large PDFs without page limits, and doesn't require JavaScript or web view dependencies.

What Common Issues Should I Watch For?

File paths on different platforms: Windows uses backslashes (C:\docs\file.pdf), macOS/Linux use forward slashes (/documents/file.pdf). Use Path.Combine() for cross-platform compatibility:

var pdfPath = Path.Combine(AppContext.BaseDirectory, "documents", "manual.pdf");
pdfView.Source = IronPdfViewSource.FromFile(pdfPath);
Enter fullscreen mode Exit fullscreen mode

Large PDF rendering: Very large PDFs (100+ MB, 500+ pages) may load slowly. Load from stream to enable progressive rendering, or display loading indicators:

activityIndicator.IsRunning = true;
pdfView.Source = IronPdfViewSource.FromFile(largePdf);
activityIndicator.IsRunning = false;
Enter fullscreen mode Exit fullscreen mode

Memory management with byte arrays: Loading PDFs from byte arrays loads the entire file into memory. For large files, prefer streaming:

// Less efficient - loads entire file into memory
byte[] bytes = File.ReadAllBytes("huge.pdf");
pdfView.Source = IronPdfViewSource.FromBytes(bytes);

// More efficient - streams from disk
using var stream = File.OpenRead("huge.pdf");
pdfView.Source = IronPdfViewSource.FromStream(stream);
Enter fullscreen mode Exit fullscreen mode

Password-protected PDFs: Currently, the viewer doesn't prompt for passwords. Decrypt PDFs before displaying or provide decrypted streams.

I've debugged MAUI apps where PDFs failed to load on macOS but worked on Windows due to file path casing issues (macOS filesystem is case-sensitive by default). Using Path.Combine() and testing on all target platforms prevented production issues.

Can I Integrate This with Navigation and Shell?

Yes, add PDF viewer pages to MAUI Shell navigation:

<!-- AppShell.xaml -->
<Shell xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
       xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
       xmlns:local="clr-namespace:MyApp">

    <TabBar>
        <Tab Title="Home">
            <ShellContent ContentTemplate="{DataTemplate local:MainPage}"
                         Route="MainPage"/>
        </Tab>
        <Tab Title="Documents">
            <ShellContent ContentTemplate="{DataTemplate local:PdfViewerPage}"
                         Route="PDFViewer"/>
        </Tab>
    </TabBar>
</Shell>
Enter fullscreen mode Exit fullscreen mode

Navigate programmatically with parameters:

await Shell.Current.GoToAsync($"PDFViewer?file={fileName}");
Enter fullscreen mode Exit fullscreen mode

In PdfViewerPage, handle query parameters:

[QueryProperty(nameof(FileName), "file")]
public partial class PdfViewerPage : ContentPage
{
    public string FileName { get; set; }

    protected override void OnAppearing()
    {
        base.OnAppearing();

        if (!string.IsNullOrEmpty(FileName))
        {
            pdfView.Source = IronPdfViewSource.FromFile(FileName);
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

This creates navigation-aware PDF viewing — users select documents from a list, app navigates to viewer page, viewer loads the selected PDF automatically.

Quick Reference

Feature Code Use Case
Load from file IronPdfViewSource.FromFile(path) Local PDFs, app resources
Load from bytes IronPdfViewSource.FromBytes(bytes) API responses, in-memory generation
Load from stream IronPdfViewSource.FromStream(stream) Large files, network streams
Show all toolbar options Options = IronPdfViewOptions.All Full-featured viewer
Hide toolbar Options = IronPdfViewOptions.None Minimal read-only view
Custom toolbar `Options = Thumbs \ Open`
Configure in app ConfigureIronPdfView() Required initialization
Licensed use ConfigureIronPdfView("KEY") Remove trial watermark

Key Principles:

  • Initialize with ConfigureIronPdfView() in MauiProgram.cs before using IronPdfView
  • Currently supports Windows and macOS desktop platforms (mobile coming soon)
  • Use Path.Combine() for cross-platform file paths
  • Stream large PDFs instead of loading byte arrays into memory
  • Customize toolbar with bitwise OR combinations of IronPdfViewOptions
  • IronPDF has no 10-page limit unlike free Spire.PDFViewer
  • Works with MAUI Shell navigation and query parameters
  • Consistent API across platforms eliminates platform-specific PDF viewing code

The complete PDF viewing guide includes examples for advanced scenarios and platform-specific optimizations.

Written by Jacob Mellor, CTO at Iron Software. Jacob created IronPDF and leads a team of 50+ engineers building .NET document processing libraries.

Top comments (0)