---
title: PdfViewer
description: PdfViewer
element: vaadin-pdf-viewer
---

## Description

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

```html
<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:

```js
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:

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

```js
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](https://vaadin.com/docs/latest/styling/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](#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](#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](#pdfviewerdocumenterrorevent)

Fired when the document could not be loaded.

### document-load

**Type:** [PdfViewerDocumentLoadEvent](#pdfviewerdocumentloadevent)

Fired when the document has loaded.

### page-changed

**Type:** [PdfViewerPageChangedEvent](#pdfviewerpagechangedevent)

Fired when the `page` property changes.

### page-count-changed

**Type:** [PdfViewerPageCountChangedEvent](#pdfviewerpagecountchangedevent)

Fired when the `pageCount` property changes.

### toolbar-collapsed-changed

**Type:** [PdfViewerToolbarCollapsedChangedEvent](#pdfviewertoolbarcollapsedchangedevent)

Fired when the `toolbarCollapsed` property changes.

### zoom-changed

**Type:** [PdfViewerZoomChangedEvent](#pdfviewerzoomchangedevent)

Fired when the `zoom` property changes.

## Types

### PdfViewerDocumentErrorEvent

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

### PdfViewerDocumentLoadEvent

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

### PdfViewerI18n

```ts
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

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

### PdfViewerPageCountChangedEvent

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

### PdfViewerToolbarCollapsedChangedEvent

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

### PdfViewerZoom

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

### PdfViewerZoomChangedEvent

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