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;

Slots #

Name	Description
toolbar-actions	Slot for application controls, e.g. buttons, at the end of the toolbar

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 #

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 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 of the previous page button.
  previousPage: 'Previous page',
  // Tooltip of the next page button.
  nextPage: 'Next page',
  // Error shown for a page that does not exist. {pageCount} is replaced with the page count.
  pageError: 'Enter 1–{pageCount}',
  // Tooltip of the zoom in button.
  zoomIn: 'Zoom in',
  // Tooltip of the zoom out button.
  zoomOut: 'Zoom out',
  // 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'
}

See also: PdfViewerI18n

page #

Type: number

The current page, starting from 1. The viewer updates it while the user scrolls, to the page that takes up most of the visible area. Setting it to another page scrolls to the start of that page. Setting it to the current page does not scroll. 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

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;
  pageError?: string;
  zoomIn?: string;
  zoomOut?: string;
  pageWidth?: string;
  pageFit?: string;
  document?: 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 }>;