| null = null;
render() {
if (this._error) {
return html`${this._error}
`;
}
return html`
${this._truncated
? html`
Showing ${this.maxPages} of ${this._totalPages} pages.
Download the PDF to see the full document.
`
: ''}
`;
}
disconnectedCallback() { // (4)
super.disconnectedCallback();
if (this._loadTask) {
this._loadTask.destroy();
this._loadTask = null;
}
}
protected updated(changed: PropertyValues) {
if (changed.has('src') && this.src) {
this._loadPdf();
}
}
private async _loadPdf() {
if (this._loadTask) {
this._loadTask.destroy();
this._loadTask = null;
}
this._error = '';
this._truncated = false;
this._totalPages = 0;
await this.updateComplete;
const container = this.shadowRoot!.querySelector('#pages') as HTMLDivElement;
if (!container) return;
container.innerHTML = '';
try {
this._loadTask = pdfjsLib.getDocument(this.src);
const pdf = await this._loadTask.promise;
this._totalPages = pdf.numPages;
const pagesToRender = Math.min(pdf.numPages, this.maxPages);
this._truncated = pdf.numPages > this.maxPages;
const availableWidth = this.clientWidth - 32; // (5)
for (let i = 1; i <= pagesToRender; i++) {
const page = await pdf.getPage(i);
const unscaled = page.getViewport({ scale: 1 });
const scale = availableWidth > 0
? availableWidth / unscaled.width
: 1.5;
const viewport = page.getViewport({ scale });
const canvas = document.createElement('canvas');
canvas.width = viewport.width;
canvas.height = viewport.height;
container.appendChild(canvas);
await page.render({
canvas,
canvasContext: canvas.getContext('2d')!,
viewport,
}).promise;
}
} catch (err: any) {
if (err?.name !== 'RenderingCancelledException') {
this._error = `Failed to load PDF: ${err?.message || err}`;
}
}
}
}
```
1. PDF.js uses a Web Worker for parsing. The worker source must be set before loading any documents.
2. The `src` property receives a URL to the PDF. Vaadin sets this attribute from the server side.
3. Hard upper limit on rendered pages. All pages are rendered up-front onto canvas elements, so a large PDF would consume a lot of memory. The default of 50 is a safe ceiling for most report-viewing use cases.
4. PDF.js holds document data in the Web Worker’s memory. Calling `destroy()` when the component is removed from the DOM prevents a memory leak.
5. The scale is computed from the container width so pages fit without horizontal scrolling. The 32px margin leaves room for the box shadow.
> **Note:** The CSS uses [Lumo](https://vaadin.com/docs/next/styling/themes/lumo/lumo-style-properties.md) theme custom properties (e.g., `--lumo-contrast-90pct`, `--lumo-font-family`). If your application uses the [Aura](https://vaadin.com/docs/next/styling/themes/aura.md) theme, replace these with the corresponding Aura custom properties.
### Server-Side Java Component
Create a `PdfViewer.java` wrapper that maps to the custom element:
```java
import com.vaadin.flow.component.Component;
import com.vaadin.flow.component.HasSize;
import com.vaadin.flow.component.Tag;
import com.vaadin.flow.component.dependency.JsModule;
import com.vaadin.flow.component.dependency.NpmPackage;
import com.vaadin.flow.server.streams.DownloadHandler;
@Tag("pdf-viewer")
@NpmPackage(value = "pdfjs-dist", version = "5.4.624") // (1)
@JsModule("./pdf-viewer.ts") // (2)
public class PdfViewer extends Component implements HasSize {
public PdfViewer() {
}
public PdfViewer(DownloadHandler downloadHandler) {
setSrc(downloadHandler);
}
public void setSrc(DownloadHandler downloadHandler) {
getElement().setAttribute("src", downloadHandler); // (3)
}
public void setMaxPages(int maxPages) {
getElement().setProperty("maxPages", maxPages); // (4)
}
}
```
1. `@NpmPackage` tells Vaadin to install `pdfjs-dist` from npm during the build.
2. `@JsModule` links to the LitElement file created above.
3. Vaadin converts a `DownloadHandler` to a URL when set as an element attribute. This is the same mechanism `IFrame` uses internally.
4. Sets the page limit on the client-side component. The default is 50.
### Using the Component
The `PdfViewer` component is a drop-in replacement for `IFrame`:
```java
PdfViewer pdfViewer = new PdfViewer(
DownloadHandler.fromInputStream(event -> {
try {
byte[] pdf = generateReport();
return new DownloadResponse(
new ByteArrayInputStream(pdf),
"report.pdf",
"application/pdf",
pdf.length);
} catch (Exception e) {
return DownloadResponse.error(500);
}
}));
pdfViewer.setWidth("100%");
pdfViewer.setHeight("800px");
add(pdfViewer);
```
The server-side API is identical to the `IFrame` version. The difference is entirely in how the browser renders the PDF.
## Choosing a Viewer
| | IFrame (Browser Viewer) | PDF Viewer Add-On | PDF.js (Custom Viewer) |
| ------------------------- | -------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------- |
| Setup | No extra dependencies | Add-on from Vaadin Directory | Requires a LitElement component + npm package |
| UI controls | Browser-provided (zoom, page nav, print, download) | Built-in (zoom, page nav, thumbnails, print, download) | You build your own (or start minimal) |
| Cross-browser consistency | Varies — each browser has a different PDF viewer | Identical rendering everywhere | Identical rendering everywhere |
| Customization | None — the viewer is a browser black box | Toolbar options and labels | Full control over layout, styling, and behavior |
| Text search | Built into most browser viewers | Built-in | Requires PDF.js text layer (extra code) |
| Mobile | Some mobile browsers don’t render PDFs inline | Works on all browsers that support `