Build a Blazor PDF viewer with Apryse WebViewer SDK

This guide shows how to build a Blazor PDF viewer using the Apryse WebViewer SDK. You'll learn how to integrate the SDK into a Blazor application to render, view, and interact with PDF documents using the WebViewer UI.

You can also download ready-to-go GitHub samples for Blazor server and Blazor wasm to get started quickly. Additionally, explore the interactive Showcase demo to see WebViewer's full capabilities in action.

Prerequisites

This guide assumes basic familiarity with Blazor development. Before you start:

• Install Node.js and npm. We recommend using the latest active LTS release.
• Install the .NET 9+ SDK for your platform to build and run your application using C#.
• Install Visual Studio Code or another code editor to develop and debug your code.
• Get your Apryse trial key.

1. Create a Blazor project

In this section, you’ll create a new Blazor application using the .NET CLI. This project provides the foundation for integrating Apryse WebViewer. If you already have a Blazor app, skip this and continue to Install WebViewer.

1. Before creating a project, open your terminal and confirm the .NET CLI is installed:

Shell

dotnet --version

If this prints a version number, you're ready to proceed. If not, install the .NET SDK and rerun the command.

1. In your terminal, go to the directory where you want to create the project.
2. Create a new webviewer-blazor project:

Shell

dotnet new blazor -o webviewer-blazor

1. Navigate to your new Blazor project directory, initialize your project, and generate a package.json file:

Shell

cd webviewer-blazor
npm init -y

Info

Flags are used to skip prompts during project configuration. The setup creates a package.json file with all default values. Select different options if preferred.

The final package.json should look like this:

JSON

{
  "name": "webviewer-blazor",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "commonjs"
}

2. Install WebViewer

Next, install the Apryse WebViewer SDK using npm. This command adds the WebViewer package to your project, allowing you to integrate the PDF viewer and editor into your Blazor application.

After navigating to your webviewer-blazor project directory, run the following command to install WebViewer:

Shell

npm i @pdftron/webviewer

3. Copy WebViewer assets

WebViewer needs access to its static assets at runtime, including WebAssembly modules, HTML, and CSS files. In a Blazor project, you must copy these assets into the public directory so they can be served correctly. For more, see Copying WebViewer static assets.

1. From your project root, create the wwwroot/lib/webviewer/public directory if it doesn't already exist:

Shell

npx --yes shx mkdir -p wwwroot/lib/webviewer/public 

1. Copy all WebViewer static assets from node_modules/@pdftron/webviewer/public into the new wwwroot/lib/webviewer/public directory:

Shell

npx --yes cpy-cli "node_modules/@pdftron/webviewer/public/**/*" wwwroot/lib/webviewer/public

1. Copy the webviewer.min.js library file from node_modules to the public directory:

Shell

npx --yes cpy-cli node_modules/@pdftron/webviewer/webviewer.min.js wwwroot/lib/webviewer/public --flat 

Your project should now include a similar structure:

webviewer-blazor/
├── Components/
├── node_modules/
├── obj/
├── Properties/
└── wwwroot/
    ├── lib/
    │   ├── bootstrap/
    │   └── webviewer/
    │       └── public/
    │           ├── core/
    │           └── ui/
    │           └── webviewer.min.js
    ├── app.css
    └── favicon.png
└── ...

4. Create the PDF viewer

In this section, you’ll add WebViewer to your Blazor app by loading the WebViewer script and creating a Razor component that initializes the viewer and renders it in the UI, where it loads and displays a document.

1. In Visual Studio Code, replace the contents of the Components/App.razor file with the following and save:

Razor

Components/App.razor

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <base href="/" />
    <link rel="stylesheet" href="@Assets["lib/bootstrap/dist/css/bootstrap.min.css"]" />
    <link rel="stylesheet" href="@Assets["app.css"]" />
    <link rel="stylesheet" href="@Assets["webviewer-blazor.styles.css"]" />
    <ImportMap />
    <link rel="icon" type="image/png" href="favicon.png" />
    <HeadOutlet />
    <!-- Load the WebViewer library from the public assets folder --> 
    <script src="@Assets["lib/webviewer/public/webviewer.min.js"]"></script>
</head>

<body>
    <Routes />
    <script src="_framework/blazor.web.js"></script>
</body>

</html>

1. Create a new Components/WebViewer.razor file, add the following code, and save:

@* Container where the WebViewer UI is rendered *@
<div id="viewer" style="width: 100%; height: 100vh; margin: 0 auto;"></div>

@* Initialize the Apryse WebViewer *@
<script>
  window.WebViewer(
    {
      // Add location of WebViewer static files
      path: '/lib/webviewer/public',
      // Add PDF to load on startup
      initialDoc: 'https://apryse.s3.amazonaws.com/public/files/samples/WebviewerDemoDoc.pdf',
      // Replace with your Apryse license key
      licenseKey: 'YOUR_LICENSE_KEY',
    },
    // Get element to mount the viewer into
    document.getElementById('viewer')
  ).then((instance) => {
    // Access the viewer API here if needed
  });
</script>

Info

If you're signed in with an Apryse account, your license key is automatically prepopulated in all code snippets.

1. Replace the Components/Pages/Home.razor file with the following and save:

Razor

Components/Pages/Home.razor

@page "/"

<WebViewer />

5. Verify your output

You can now load and display a PDF document in the WebViewer UI. Run your Blazor application to launch WebViewer and see the PDF in your browser.

1. From your project directory, run the following command to start the application:

Shell

dotnet run

A successful output looks similar to:

Shell

Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5067
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: /path/to/your/project

1. Open the localhost URL from your terminal to view the WebViewer UI and PDF document.

Troubleshooting

WebViewer fails to load due to MIME type issues

If WebViewer doesn't load or you see a blank or partially rendered UI, the server may not be serving certain file types correctly. WebViewer includes files with .wasm, .gz, and .br extensions, which require proper MIME types that aren't always configured by default in Blazor.

To fix this, configure the application to serve these file types by updating Program.cs:

C#

Program.cs

var provider = new FileExtensionContentTypeProvider();
provider.Mappings[".res"] = "application/octet-stream";
provider.Mappings[".pexe"] = "application/x-pnacl";
provider.Mappings[".nmf"] = "application/octet-stream";
provider.Mappings[".mem"] = "application/octet-stream";
provider.Mappings[".wasm"] = "application/wasm";
provider.Mappings[".gz"] = "application/gzip";
provider.Mappings[".br"] = "application/brotli";

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(Directory.GetCurrentDirectory(), "wwwroot")),
        ContentTypeProvider = provider
});

Restart the application after making these changes.

Get started video

In this 5-minute video, learn how to install and integrate the Apryse WebViewer SDK into a Blazor project.

Integrate the WebViewer SDK into an ASP.NET Core–hosted Blazor project.

Next steps

UsageGuidesSamplesAPI docs