Docs

Documentation versions (currently viewingVaadin 25.4 (pre-release))

PDF Viewer

PDF Viewer shows PDF documents in the application, with page navigation, zoom and download.
Note
Commercial Feature

A commercial Vaadin subscription is required to use PDF Viewer in your project.

PDF Viewer shows PDF documents in the application. Users can scroll through the pages, go to a page, zoom, select text, follow links, and download the document.

Note
Preview Feature

This is a preview version of PDF Viewer. You need to enable it with the feature flag com.vaadin.experimental.pdfViewerComponent. Preview versions may lack some planned features, and breaking changes may be introduced in any Vaadin version. We encourage you to try it out and provide feedback in the Forum so that we can make it stable. You can report bugs and request additional features on GitHub.

Note
On Safari and iOS Safari, PDF Viewer requires version 18 or newer, one version above the Vaadin minimum. Chrome, Edge and Firefox are supported as for all Vaadin components.
Source code
PdfViewerBasic.java
pdf-viewer-basic.tsx
pdf-viewer-basic.ts

Document Source

The viewer loads the document from a URL. In Flow, the document can also be served from the application with a download handler, as in the example above.

Source code
Java
PdfViewer viewer = new PdfViewer("/files/report.pdf");

// Or serve the document from the application
viewer.setSrc(DownloadHandler.forClassResource(getClass(),
        "/documents/report.pdf", "report.pdf"));
HTML
tsx

The viewer fetches the whole document with a single GET request, without range requests. A new source replaces the current document, and the viewer shows its first page.

Note
A URL on another origin works only if its server allows the request with Cross-Origin Resource Sharing (CORS) headers.

File Name

The viewer shows the file name in the header and uses it for the downloaded file. By default, the file name comes from the Content-Disposition header of the response set by a Flow download handler, or else from the end of the URL path. The file name can also be set explicitly:

Source code
Java
viewer.setFileName("annual-report.pdf");
HTML
tsx

Header & Toolbar

The header shows a title for the document, which defaults to the file name and can be customized. Clicking the header toggles the toolbar. The toolbar can be also collapsed programmatically.

Source code
PdfViewerHeader.java
pdf-viewer-header.tsx
pdf-viewer-header.ts

The header can also be hidden. The toolbar is then always shown, even when it is collapsed.

Source code
Java
viewer.setHeaderVisible(false);
HTML
tsx

Users can navigate through the document by scrolling, using the previous and next page buttons, or the page field toolbar. It is also possible to scroll to a page programmatically.

The viewer keeps track of the current page and the page count. The current page is the page with the largest part of it in view.

Source code
PdfViewerNavigation.java
pdf-viewer-navigation.tsx
pdf-viewer-navigation.ts

Zoom

By default, the width of the current page fits the viewer. It can be customized to fit the whole page.

Source code
PdfViewerZoom.java
pdf-viewer-zoom.tsx
pdf-viewer-zoom.ts

The pages can also be shown at a fixed scale relative to their actual size, for example 150%:

Source code
Java
viewer.setZoom(Zoom.of(1.5));
HTML
tsx

The fit levels follow the size of the viewer when it resizes. The zoom level stays when the document changes. Users change the zoom with the toolbar controls or keyboard shortcuts.

Download

The download button of the toolbar saves the document with its original bytes, so digital signatures stay intact. The viewer does not request the document again for the download.

The download button can be hidden, and the download can be started from the application instead. If the document is still loading, the download starts once it has loaded.

Source code
Java
viewer.setDownloadButtonVisible(false);

// Start the download, for example from a button
viewer.download();
TypeScript
tsx

Toolbar Actions

Custom controls, such as buttons, can be added to the toolbar and placed after the zoom controls.

Source code
PdfViewerToolbarActions.java
pdf-viewer-toolbar-actions.tsx
pdf-viewer-toolbar-actions.ts

Loading & Errors

The viewer notifies the application when a document has loaded, with the page count and the title of the document. It also notifies the application when a document cannot be loaded, with the reason:

  • network: the document could not be fetched.

  • invalid: the file is not a valid PDF document.

  • password: the document is protected with a password.

Source code
Java
viewer.addDocumentLoadListener(event ->
        Notification.show("Loaded " + event.getPageCount() + " pages"));

viewer.addDocumentErrorListener(event -> {
    if (event.getReason() == DocumentErrorReason.PASSWORD) {
        Notification.show("The document is protected with a password");
    }
});
HTML
tsx

The viewer renders the pages with the pdf.js library, which runs in a web worker. If the application has a Content Security Policy, its worker-src directive has to allow the worker script.

Accessibility

Each page has a text layer over its image. Users can select the text, and screen readers read it. The viewer keeps the text layer only for the pages near the view. Therefore, screen readers reach only the text of these pages.

Links in the document are focusable. A link to another page of the document scrolls to that page. Links with the http:, https:, and mailto: schemes open in a new tab.

A tagged PDF describes the structure of its content, such as headings, lists, tables, and figures. The viewer passes this structure to screen readers.

Keyboard Usage

The page area is focusable once a document has loaded. The following shortcuts work while the focus is in the viewer:

Keys Action

Ctrl+Plus or Cmd+Plus

Zooms in.

Ctrl+Minus or Cmd+Minus

Zooms out.

Ctrl+0 or Cmd+0

Fits the page width to the viewer.

Ctrl+Home or Cmd+Home

Goes to the first page, while the page area has focus.

Ctrl+End or Cmd+End

Goes to the last page, while the page area has focus.

Internationalization (i18n)

The texts of the viewer can be localized, such as the tooltips of the toolbar buttons and the zoom options. Set only the texts that you want to change. The defaults apply to the others.

Source code
Java
viewer.setI18n(new PdfViewerI18n()
        .setPreviousPage("Edellinen sivu")
        .setNextPage("Seuraava sivu")
        .setDownload("Lataa"));
TypeScript
tsx

Some texts have a placeholder, such as {page}, that the viewer replaces with a value. The Flow PdfViewerI18n class has the following texts. Lit and React have the page, zoom, pageLabel and loading texts in addition.

Text Default value

previousPage

Previous page

nextPage

Next page

pageError

Enter 1–{pageCount}

zoomIn

Zoom in

zoomOut

Zoom out

pageWidth

Page width

pageFit

Page fit

document

PDF document

link

Link

goToPage

Go to page {page}

externalLink

{text} (opens in a new tab)

download

Download