PdfViewer

Description #

<vaadin-pdf-viewer> is a web component for viewing PDF documents.

<vaadin-pdf-viewer src="/files/report.pdf"></vaadin-pdf-viewer>

The component is experimental and its API may change. To use it, enable the following feature flag:

window.Vaadin.featureFlags.pdfViewerComponent = true;

Customization #

You can add application controls to the toolbar by using slot names.

Slot name	Description
toolbar-actions	Application controls, e.g. buttons, at the end of the toolbar, before the download button.

Example #

A custom button that replaces the download button:

<vaadin-pdf-viewer src="/files/report.pdf" download-button-hidden>
  <vaadin-button slot="toolbar-actions">Save a copy</vaadin-button>
</vaadin-pdf-viewer>

const viewer = document.querySelector('vaadin-pdf-viewer');
viewer.querySelector('vaadin-button').addEventListener('click', () => {
  viewer.download();
});

Styling #

The following shadow DOM parts are available for styling:

Part name	Description
header	The header above the toolbar, a button that collapses and expands it, see headerHidden.
title	The title in the header.
header-toggle	The icon in the header that shows whether the toolbar is collapsed.
toolbar	The toolbar above the pages.
toolbar-group	A group of related controls in the toolbar: navigation, zoom and actions.
content	The scrollable area that contains the pages.
page	A page of the document.
loader	The loading indicator shown while the document loads.

The following state attributes are available for styling:

Attribute	Description
loading	Set while the document is loading.
has-error	Set when the document could not be loaded.
focused	Set when the page area is focused.
focus-ring	Set when the page area is focused using the keyboard.

The following custom CSS properties are available for styling:

Custom CSS property
--vaadin-pdf-viewer-background
--vaadin-pdf-viewer-border-color
--vaadin-pdf-viewer-border-radius
--vaadin-pdf-viewer-padding
--vaadin-pdf-viewer-page-background
--vaadin-pdf-viewer-page-gap
--vaadin-pdf-viewer-page-shadow
--vaadin-pdf-viewer-text-color
--vaadin-pdf-viewer-toolbar-background
--vaadin-pdf-viewer-toolbar-gap
--vaadin-pdf-viewer-toolbar-padding

See Styling Components documentation.

Properties #

downloadButtonHidden #

Type: boolean

Whether the button that downloads the document is hidden from the toolbar. The download() method works also while it is hidden.

fileName #

Type: string | null | undefined

The name of the file that download() saves, used as given, which the header also shows. When not set, the name is the PDF file name from the Content-Disposition header of the response, else the PDF file name at the end of the path of src, else document.pdf.

headerHidden #

Type: boolean

Whether the header above the toolbar is hidden. The header shows headerTitle, or else the name of the document, and collapses and expands the toolbar when clicked.

headerTitle #

Type: string | null | undefined

The title shown in the header, see headerHidden. When not set, the header shows fileName, else the PDF file name from the Content-Disposition header of the response, else the PDF file name at the end of the path of src, else the document text of i18n.

i18n #

Type: PdfViewerI18n | undefined

The object used to localize this component. To change the default localization, set this to an object that provides all properties, or just the individual properties you want to change.

When not set, defaults to undefined.

The object has the following JSON structure and default values:

{
  // Tooltip and accessible name of the previous page button, and accessible name of a link to the previous page.
  previousPage: 'Previous page',
  // Tooltip and accessible name of the next page button, and accessible name of a link to the next page.
  nextPage: 'Next page',
  // Accessible name of the page field.
  page: 'Page',
  // Error shown for a page that does not exist. {pageCount} is replaced with the page count.
  pageError: 'Enter 1–{pageCount}',
  // Tooltip and accessible name of the zoom in button.
  zoomIn: 'Zoom in',
  // Tooltip and accessible name of the zoom out button.
  zoomOut: 'Zoom out',
  // Accessible name of the zoom select.
  zoom: 'Zoom',
  // Zoom select item that fits the page width to the viewer.
  pageWidth: 'Page width',
  // Zoom select item that fits the whole page into the viewer.
  pageFit: 'Page fit',
  // Title of the header for a document without a file name.
  document: 'PDF document',
  // Accessible name of a page. {page} is replaced with the page number.
  pageLabel: 'Page {page}',
  // Accessible name of the loading indicator.
  loading: 'Loading',
  // Accessible name of a link without text whose destination is unknown.
  link: 'Link',
  // Accessible name of a link without text to another page. {page} is replaced with the page number.
  goToPage: 'Go to page {page}',
  // Accessible name of a link that opens in a new tab. {text} is replaced with the text of the link, or its URL.
  externalLink: '{text} (opens in a new tab)',
  // Tooltip and accessible name of the download button.
  download: 'Download'
}

See also: PdfViewerI18n

page #

Type: number

The current page, starting from 1. The viewer updates it while the user scrolls, to the page with the largest part of it in view, or, for a page taller than the view, the largest part of the view. Setting it to another page scrolls to the start of that page. Setting it to the current page does not scroll, see scrollToPage(). A value that is not a page of the document logs a warning and does not scroll. A set value stays as it is until the user scrolls. A new src resets it to 1, unless page is set in the same update.

pageCount #

Type: number

The number of pages in the loaded document, or 0 when no document is loaded.

src #

Type: string | null | undefined

The URL of the PDF document to show.

toolbarCollapsed #

Type: boolean

Whether the toolbar is collapsed. The header collapses and expands it, so the toolbar collapses only while the header is shown, see headerHidden.

zoom #

Type: PdfViewerZoom

The zoom level of the pages:

• page-width (default) fits the width of the current page to the viewer.
• page-fit fits the whole current page into the viewer.
• A number scales the pages relative to their actual size, e.g. 1 for 100%.

The fit follows the current page when the zoom is set, when the viewer resizes and when the page gets its own size. Scrolling to a page of another size keeps the scale.

An invalid value logs a warning and is replaced with page-width.

See also: PdfViewerZoom

Methods #

download #

Type: () => void

Downloads the document. The file has the original bytes of the document, so the viewer does not request it again, and signatures stay intact. The file name is fileName when set, else the name from the response or src, see fileName. While the document loads, it is downloaded once loaded. When src changes meanwhile, also in the same task, the new document is downloaded. Does nothing without a document, or when the viewer is not attached.

scrollToPage #

Type: (page: number) => void

Scrolls to the start of the given page.

Right after setting src, it scrolls once the document has loaded, and in a hidden viewer, once the viewer is shown. Does nothing without a document or when the viewer is not attached.

Events #

document-error #

Type: PdfViewerDocumentErrorEvent

Fired when the document could not be loaded.

document-load #

Type: PdfViewerDocumentLoadEvent

Fired when the document has loaded.

page-changed #

Type: PdfViewerPageChangedEvent

Fired when the page property changes.

page-count-changed #

Type: PdfViewerPageCountChangedEvent

Fired when the pageCount property changes.

toolbar-collapsed-changed #

Type: PdfViewerToolbarCollapsedChangedEvent

Fired when the toolbarCollapsed property changes.

zoom-changed #

Type: PdfViewerZoomChangedEvent

Fired when the zoom property changes.

Types #

PdfViewerDocumentErrorEvent #

/**
 * Fired when the document could not be loaded.
 */
export type PdfViewerDocumentErrorEvent = CustomEvent<{ reason: 'invalid' | 'network' | 'password'; error: unknown }>;

PdfViewerDocumentLoadEvent #

/**
 * Fired when the document has loaded.
 */
export type PdfViewerDocumentLoadEvent = CustomEvent<{ pageCount: number; title: string }>;

PdfViewerI18n #

export interface PdfViewerI18n {
  previousPage?: string;
  nextPage?: string;
  page?: string;
  pageError?: string;
  zoomIn?: string;
  zoomOut?: string;
  zoom?: string;
  pageWidth?: string;
  pageFit?: string;
  document?: string;
  pageLabel?: string;
  loading?: string;
  link?: string;
  goToPage?: string;
  externalLink?: string;
  download?: string;
}

PdfViewerPageChangedEvent #

/**
 * Fired when the `page` property changes.
 */
export type PdfViewerPageChangedEvent = CustomEvent<{ value: number }>;

PdfViewerPageCountChangedEvent #

/**
 * Fired when the `pageCount` property changes.
 */
export type PdfViewerPageCountChangedEvent = CustomEvent<{ value: number }>;

PdfViewerToolbarCollapsedChangedEvent #

/**
 * Fired when the `toolbarCollapsed` property changes.
 */
export type PdfViewerToolbarCollapsedChangedEvent = CustomEvent<{ value: boolean }>;

PdfViewerZoom #

export type PdfViewerZoom = 'page-fit' | 'page-width' | number;

PdfViewerZoomChangedEvent #

/**
 * Fired when the `zoom` property changes.
 */
export type PdfViewerZoomChangedEvent = CustomEvent<{ value: PdfViewerZoom }>;