Pixata.Blazor.PdfViewer
1.1.0
dotnet add package Pixata.Blazor.PdfViewer --version 1.1.0
NuGet\Install-Package Pixata.Blazor.PdfViewer -Version 1.1.0
<PackageReference Include="Pixata.Blazor.PdfViewer" Version="1.1.0" />
<PackageVersion Include="Pixata.Blazor.PdfViewer" Version="1.1.0" />
<PackageReference Include="Pixata.Blazor.PdfViewer" />
paket add Pixata.Blazor.PdfViewer --version 1.1.0
#r "nuget: Pixata.Blazor.PdfViewer, 1.1.0"
#:package Pixata.Blazor.PdfViewer@1.1.0
#addin nuget:?package=Pixata.Blazor.PdfViewer&version=1.1.0
#tool nuget:?package=Pixata.Blazor.PdfViewer&version=1.1.0
Pixata.Blazor.PdfViewer 

PixataPdfViewer shows a PDF in a Blazor page, with page navigation, zoom (fit width, fit page and percentages), rotation, text that can be selected and searched, and download and print buttons. Users can mark it up with notes, highlights, strike-through, drawing and text, which is kept apart from the PDF. It fills its container, so it can sit beside a form in a split layout, which is what it was written for: checking invoices against the details typed in from them.
The PDF is drawn by PDF.js, Mozilla's PDF engine, which is part of this package, so nothing is loaded from a CDN. It works in Blazor Server and WebAssembly, and is styled by the same --pixata-blazor-* variables as the components in Pixata.Blazor, which it uses for its toolbar.
It's a separate package because PDF.js and the files it needs come to about 5MB. They're only downloaded by a browser that shows a PDF, but they'd be in every app that uses Pixata.Blazor.
See the live demo for how it looks, and the source for that page for the code.
Version 1.1.0 adds mark-up: notes, highlights, strike-through, freehand drawing and text, with who added each and when. It's kept apart from the PDF, as a list you store yourself, and Pixata.Pdf's
PdfMarkupFlattenercan draw it into a copy of the PDF (#140).Version 1.0.0 is the first release (#139).
Contents
- Setup
- Basic use
- Where the PDF comes from
- Size and layout
- The toolbar
- Pages and zoom
- Mark-up
- Events
- Parameters
- Methods and properties
- Translating
- Styling
- Content Security Policy
- How it works
Setup
Install the package, add its stylesheet to your host page after Pixata.Blazor's...
<link rel="stylesheet" href="_content/Pixata.Blazor/pixata.css" />
<link rel="stylesheet" href="_content/Pixata.Blazor.PdfViewer/pixata-pdfviewer.css" />
...and add @using Pixata.Blazor.PdfViewer to your _Imports.razor. There's nothing to register. PDF.js's own styles, which lay out the pages and their text, are added to the page by the viewer's script when it's first used.
Basic use
<div style="height: 80vh;">
<PixataPdfViewer Url="api/invoices/1042/pdf" FileName="INV-1042.pdf" />
</div>
Where the PDF comes from
Give the viewer one of these. Giving more than one throws an InvalidOperationException, and giving none shows "No document".
| Parameter | Type | Description |
|---|---|---|
Url |
string? |
A URL the browser fetches the PDF from. It can be an endpoint of your app that the user's cookies give access to. A URL on another site needs that site to allow it with CORS. PDF.js asks for the parts of the file it needs as it needs them, if the server supports range requests, so the first page of a large PDF shows quickly |
Data |
byte[]? |
The PDF itself, say from a database. It's streamed to the browser, so a large file doesn't have to fit in one SignalR message |
Stream |
Stream? |
A stream to read the PDF from. It's read from its current position, and isn't disposed, so dispose of it yourself afterwards |
Setting a different URL, array or stream shows the new PDF. While it's loading, the viewer says "Loading...", and if it can't be shown, the viewer says why (see events).
Size and layout
By default the viewer fills the width and height of its container, and is at least --pixata-blazor-pdfviewer-min-height (20rem) tall, so give the container a height. Height and Width set the size instead, as CSS sizes.
To show the PDF beside a form, put both in a grid...
<div style="display: grid; grid-template-columns: 3fr 2fr; gap: 1rem; height: calc(100vh - 8rem);">
<PixataPdfViewer Data="_invoice.Pdf" FileName="@($"{_invoice.Number}.pdf")" Zoom="PixataPdfViewerZoom.FitPage" />
<EditForm Model="_invoice" OnValidSubmit="Approve">
...
</EditForm>
</div>
When the viewer changes size, a fitted zoom is worked out again, so the pages still fit.
The toolbar
From left to right, the toolbar has...
- the previous and next page buttons, with a box showing the page number, which you can type a page number into
- the zoom out and zoom in buttons, with a drop-down of fit width, fit page and percentages from 50% to 400%
- the rotate anticlockwise and clockwise buttons, which only change how the pages are shown, not the PDF
- the search box. Matches are highlighted on every page, and the box says how many there are. Enter goes to the next match and Shift+Enter to the previous one, as do the up and down buttons
- the mark-up tools and their colour, if you've said who the user is
- the download and print buttons
ShowSearch, ShowRotate, ShowDownload and ShowPrint turn parts off, and ShowToolbar="false" turns it all off. When the toolbar is too narrow for everything, it wraps onto a second line.
As well as the toolbar, the pages can be scrolled with the mouse, the keyboard (once the pages have the focus) or a finger. Holding Ctrl and turning the mouse wheel, or a pinch on a touchpad, zooms around the pointer. The text can be selected and copied, and links in the PDF work: one to another page goes to it, and one to a web site opens in a new tab.
Printing draws each page as an image at 150 dots per inch, with its mark-up if that's shown, and prints them from a hidden frame. That works the same in every browser, which handing the PDF to the browser's own viewer doesn't. The print button is busy while the pages are drawn. Downloading gives the PDF as it is, without the mark-up; to download it with the mark-up, see keeping the mark-up.
Pages and zoom
Page is the page shown, counting from 1. Bind it to know which page the user is on, and set it to show a page...
<PixataPdfViewer Data="_pdf" @bind-Page="_page" />
<p>Page @_page</p>
<button @onclick="() => _page = 3">Show the delivery note</button>
Zoom is how big the pages are shown...
Zoom |
Pages shown |
|---|---|
PixataPdfViewerZoom.FitWidth |
As wide as the viewer (the default) |
PixataPdfViewerZoom.FitPage |
Each page fits inside the viewer, so a whole page can be seen at once |
A number, such as 1.5m or PixataPdfViewerZoom.Scale(1.5m) |
At that scale, where 1 is 100%. It's kept between 0.1 and 25 |
Each PDF is opened at Page, or at its last page if it hasn't that many, in which case PageChanged says so. So when you show another PDF, set Page back to 1 as well if you bind it. Changing either parameter changes what's shown. A parent that sets them without binding them, such as Zoom="1m", doesn't undo what the user has done whenever it renders, as only a change to the parameter's value counts.
Mark-up
Users can mark up the PDF, say to query a figure on an invoice or correct one, with...
| Tool | How it's used |
|---|---|
| Add a note | Click where the note goes, and type it. The note is shown as a marker, which anyone can click to read it |
| Highlight | Select some text, or drag a box over part of the page that has none, such as part of a scanned page |
| Strike through | The same as highlight, with a line through the text instead. On a page whose text runs down it, the line runs down too |
| Draw | Draw with the mouse, a pen or a finger. Lines drawn within a second or so of each other make one drawing |
| Add text | Click where the text goes, and type it. Enter starts a new line, and Ctrl+Enter or clicking away saves it |
Each tool stays chosen until you click it again or press Escape, so you can add several notes in a row, say. The colour picker beside the tools sets the colour, one for highlights and another for the rest. With no tool chosen, clicking some mark-up shows who added it and when, in the browser's time zone, with the text of a note. The user can change the text of their own notes and text, and delete their own mark-up, there. Escape closes it without saving any change, and emptying a note's text deletes it.
The mark-up is kept apart from the PDF, which is never changed. It's a list of PdfMarkupItems (from Pixata.Extensions, in Pixata.Extensions.Pdf), which you store, say as JSON next to the PDF, and give back to the viewer the next time it's shown...
<PixataPdfViewer Url="@($"api/invoices/{Id}/pdf")" @bind-Markup="_markup" MarkupAuthor="@_user.Name" MarkupAuthorId="@_user.Id"
OnMarkupChanged="SaveMarkup" />
@code {
private IReadOnlyList<PdfMarkupItem> _markup = [];
protected override async Task OnInitializedAsync() =>
_markup = PdfMarkup.FromJson(await InvoiceService.GetMarkup(Id));
private Task SaveMarkup(PixataPdfViewerMarkupChangedEventArgs args) =>
InvoiceService.SaveMarkup(Id, PdfMarkup.ToJson(args.Markup));
}
PdfMarkup.ToJson() and PdfMarkup.FromJson() use camel case names and the kinds of mark-up as strings, so the JSON is easy to read, and to query in a database that understands JSON. The coordinates are the page's own, in points from its bottom left, as a PDF's annotations are, so they don't depend on the zoom or rotation, and mark-up added on a phone lines up on a desktop.
Who can change what
MarkupAuthorturns the tools on. It's the user's name, which is recorded with what they add. Without it, the mark-up is shown, but there are no tools and nothing can be changed, so a viewer for someone who can only look needs nothing more.ShowMarkup="false"hides the mark-up and the tools.- Users can only change and delete their own mark-up. That's mark-up whose
AuthorIdisMarkupAuthorId, if you set it, or whoseAuthorisMarkupAuthorif you don't. SetMarkupAuthorId(say to the user's id) if two people could have the same name. - The component checks, not just the script, so in Blazor Server a user can't add mark-up, or change someone else's, by changing the page. In WebAssembly, as with anything that runs in the browser, check again on the server before you save.
- The viewer gives each new item its
Id,Author,AuthorIdandCreatedtime (in UTC), and setsModifiedwhen its text is changed, whatever the script says.
Mark-up events
MarkupChanged gives the whole new list, for @bind-Markup, and OnMarkupChanged gives a PixataPdfViewerMarkupChangedEventArgs, with...
| Property | Description |
|---|---|
Item |
The item added, changed or deleted |
Change |
Added, Changed or Deleted |
Markup |
All the mark-up, now |
Each change makes a new list, so the one you gave the viewer isn't changed. The viewer only takes the mark-up from the parameter when you give it a different list, so a parent that doesn't bind it doesn't lose what the user adds whenever it renders. To change the mark-up from code, give it a new list.
Keeping the mark-up
To archive the PDF with its mark-up, or send it to someone, draw the mark-up into a copy of it with PdfMarkupFlattener from Pixata.Pdf. It looks as it does in the viewer, with the notes numbered on the page and listed, with who wrote them and when, on a page at the end.
ApiResponse<byte[]> marked = PdfMarkupFlattener.Flatten(pdf, PdfMarkup.FromJson(json));
Events
| Event | Arguments | Fires |
|---|---|---|
OnLoaded |
PixataPdfViewerLoadedEventArgs, with PageCount |
When a PDF has been opened |
OnError |
PixataPdfViewerErrorEventArgs, with Kind and Detail |
When a PDF can't be shown. Kind is PasswordProtected, NotAPdf, NotFound or Other (a network failure, say), and Detail is PDF.js's description, for a log. The viewer shows a message as well |
OnDownload |
PixataPdfViewerDownloadEventArgs, with FileName and IsCancelled |
When the download button is clicked, before the PDF is downloaded. Change FileName, or set IsCancelled to do something else instead |
PageChanged |
int |
When the page shown changes. Use @bind-Page |
MarkupChanged |
IReadOnlyList<PdfMarkupItem> |
When the user adds, changes or deletes mark-up. Use @bind-Markup |
OnMarkupChanged |
PixataPdfViewerMarkupChangedEventArgs, with Item, Change and Markup |
The same, saying what changed. See mark-up |
private void Downloading(PixataPdfViewerDownloadEventArgs args) =>
args.FileName = $"{_invoice.Supplier} {_invoice.Number}.pdf";
PDFs protected by a password can't be shown yet.
Parameters
| Parameter | Type | Description |
|---|---|---|
Url, Data, Stream |
The PDF. See where the PDF comes from | |
FileName |
string |
The name the PDF is saved as when it's downloaded. Defaults to document.pdf |
Zoom |
PixataPdfViewerZoom |
How big the pages are shown. Defaults to FitWidth |
Page |
int |
The page shown, counting from 1. Use @bind-Page |
ShowToolbar |
bool |
Shows the toolbar. Defaults to true |
ShowSearch, ShowRotate, ShowDownload, ShowPrint |
bool |
Show those parts of the toolbar. Default to true |
Markup |
IReadOnlyList<PdfMarkupItem>? |
The mark-up. Use @bind-Markup |
MarkupAuthor |
string? |
The user's name, recorded with the mark-up they add. The mark-up tools are only shown when it's set |
MarkupAuthorId |
string? |
The user's id. When it's set, users can change the mark-up with their id, rather than their name |
ShowMarkup |
bool |
Shows the mark-up, and the tools. Defaults to true |
Height, Width |
string? |
The viewer's size, as CSS sizes. By default it fills its container |
Class |
string? |
Extra classes for the outer element |
Id |
string? |
The outer element's id |
Messages |
PixataPdfViewerMessages? |
The text the viewer shows, for translating |
Methods and properties
| Member | Description |
|---|---|
GoToPage(int page) |
Shows a page, counting from 1 |
SetZoom(PixataPdfViewerZoom zoom) |
Sets the zoom |
Rotate(bool clockwise = true) |
Turns the pages a quarter turn |
Search(string text) |
Searches for some text, highlighting every match and showing the first. An empty string clears the search |
SearchNext(), SearchPrevious() |
Show the next or previous match |
Download() |
Downloads the PDF, raising OnDownload first |
Print() |
Prints the PDF |
SetMarkupTool(PixataPdfViewerMarkupTool tool) |
Chooses a mark-up tool (Note, Highlight, StrikeThrough, Ink or Text), or puts it down (None), as the toolbar does. It's ignored unless MarkupAuthor is set |
IsLoaded |
Whether a PDF is being shown |
PageCount |
The number of pages, or 0 if there's no PDF |
CurrentPage |
The page shown |
CurrentMarkup |
The mark-up, with what the user has added |
MarkupTool |
The mark-up tool chosen |
<PixataPdfViewer @ref="_viewer" Url="@_url" />
<button @onclick="() => _viewer.Search(_invoice.Number)">Find the invoice number</button>
@code {
private PixataPdfViewer _viewer = null!;
}
Translating
Give the viewer a PixataPdfViewerMessages with your own text. Its properties are the buttons' tooltips and accessible names, the drop-down's options, the messages, and the text of the mark-up's pop-up (NewNote, NotePlaceholder, DeleteMarkup, CloseMarkup and so on). PageCountFormat ("of {0}") and MatchesFormat ("{0} of {1}") are format strings...
<PixataPdfViewer Url="@_url" Messages="_french" />
@code {
private static readonly PixataPdfViewerMessages _french = new() {
PreviousPage = "Page précédente",
NextPage = "Page suivante",
PageCountFormat = "sur {0}",
Search = "Rechercher",
NoMatches = "Aucun résultat"
};
}
Styling
The viewer is styled by these custom properties, which you can set on :root or, with Class, on a particular viewer, as well as the shared --pixata-blazor-* ones (text colour, font, border radius and so on)...
| Property | Default |
|---|---|
--pixata-blazor-pdfviewer-min-height |
20rem |
--pixata-blazor-pdfviewer-border-color |
--pixata-blazor-input-border-color |
--pixata-blazor-pdfviewer-toolbar-bg |
--pixata-blazor-surface-alt-bg |
--pixata-blazor-pdfviewer-bg |
#e9ecef, behind the pages |
--pixata-blazor-pdfviewer-page-shadow |
A small shadow under each page |
--pixata-blazor-pdfviewer-page-gap |
.75rem, between the pages |
--pixata-blazor-pdfviewer-match-bg |
A pale yellow, behind each search match |
--pixata-blazor-pdfviewer-current-match-bg |
An orange, behind the match being shown |
--pixata-blazor-pdfviewer-markup-selected-color |
--pixata-blazor-primary, the glow around mark-up that's shown in the pop-up |
--pixata-blazor-pdfviewer-popover-width |
18rem, the width of the mark-up's pop-up |
The elements have these classes...
| Class | Element |
|---|---|
pixata-blazor-pdfviewer |
The outer element |
pixata-blazor-pdfviewer-toolbar |
The toolbar, made of groups of tools (pixata-blazor-pdfviewer-tools) |
pixata-blazor-pdfviewer-body |
Everything under the toolbar |
pixata-blazor-pdfviewer-container |
The scrolling area the pages are in. Inside it, the pages are PDF.js's .pdfViewer .page |
pixata-blazor-pdfviewer-status |
The message shown while there's no PDF to show, with pixata-blazor-pdfviewer-error for an error |
pixata-blazor-pdfviewer-markup-tools |
The mark-up tools, with pixata-blazor-pdfviewer-chosen on the one chosen, and pixata-blazor-pdfviewer-colour on the colour picker |
pixata-blazor-pdfviewer-markup |
The SVG over each page that the mark-up is drawn in. Each item is a pixata-blazor-pdfviewer-markup-item, with pixata-blazor-pdfviewer-markup-note, -highlight, -strikethrough, -ink or -text |
pixata-blazor-pdfviewer-popover |
The pop-up that shows a note, or other mark-up that's been clicked |
pixata-blazor-pdfviewer-text-editor |
The box text is typed into on the page |
Content Security Policy
If your app has a Content Security Policy, the viewer needs...
worker-src 'self', for PDF.js's worker, which reads the PDF away from the pagescript-src 'wasm-unsafe-eval', for the image decoders that some PDFs need (scanned documents often use JBIG2 or JPEG 2000 images). Without it, PDF.js falls back to slower JavaScript decodersimg-src blob:, for printing, and for printing the mark-upconnect-srcto include wherever aUrlpoints
How it works
The component renders the toolbar and an empty scrolling area, and the script (wwwroot/pdfjs/pixata-pdfviewer.js) has PDF.js's viewer draw the pages in that area, telling the component the page, zoom and search matches as they change. Pages are drawn as they're scrolled to, so a long PDF opens quickly.
The mark-up is drawn as an SVG over each page, by the script. The component holds the list, and sends it to the script whenever it changes. When the user adds, changes or deletes something, the script tells the component, which checks they may, records it, and sends the list back.
The script is PDF.js 6.5 and a little code of this package's, bundled into one file. It's built from build/pixata-pdfviewer, which explains how to rebuild it. Next to it are PDF.js's worker, its styles, and the files it loads only when a PDF needs them: character maps for Chinese, Japanese and Korean text, the standard fonts for PDFs that don't include their own, and the image decoders. Each is used under its own licence, which is next to it: PDF.js under the Apache License 2.0, and the rest under BSD, MIT and SIL Open Font licences.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Pixata.Blazor (>= 5.29.1)
- Pixata.Extensions (>= 2.25.0)
-
net8.0
- Pixata.Blazor (>= 5.29.1)
- Pixata.Extensions (>= 2.25.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.1.0 | 158 | 11/18/2026 |