Interfaces

CanvasLoadedCallback

This callback function will run after a particular page is rendered. It provides sizes of both canvas object and PDF page so that one may add more object(s) to that page's canvas layer.

function	description
(canvasElement: HTMLCanvasElement, viewport: ViewportDimensions) => void	Callback function to call after the canvas element is rendered

CharacterMap

Key	Description	Type
url	The URL or relative path where the predefined Adobe CMaps are located. It must have / at the end.	string
isCompressed	Specify if the Adobe CMaps are binary packed. The default value is true.	boolean

Composition TS

<script setup lang="ts">
import { VPdfViewer } from "@vue-pdf-viewer/viewer";

const pdfFileSource =
  "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf";
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer
      :src="pdfFileSource"
      :character-map="{
        url: 'https://cdn.jsdelivr.net/npm/pdfjs-dist@2.0.288/cmaps/',
        isCompressed: true,
      }"
    />
  </div>
</template>

Composition JS

<script setup>
import { VPdfViewer } from "@vue-pdf-viewer/viewer";

const pdfFileSource =
  "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf";
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer
      :src="pdfFileSource"
      :character-map="{
        url: 'https://cdn.jsdelivr.net/npm/pdfjs-dist@2.0.288/cmaps/',
        isCompressed: true,
      }"
    />
  </div>
</template>

Options TS

<script lang="ts">
import { defineComponent } from "vue";
import { VPdfViewer } from "@vue-pdf-viewer/viewer";

export default defineComponent({
  components: { VPdfViewer },
  data() {
    return {
      pdfFileSource:
        "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf",
    };
  },
});
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer
      :src="pdfFileSource"
      :character-map="{
        url: 'https://cdn.jsdelivr.net/npm/pdfjs-dist@2.0.288/cmaps/',
        isCompressed: true,
      }"
    />
  </div>
</template>

Options JS

<script>
import { VPdfViewer } from "@vue-pdf-viewer/viewer";

export default {
  components: { VPdfViewer },
  data() {
    return {
      pdfFileSource:
        "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf",
    };
  },
};
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer
      :src="pdfFileSource"
      :character-map="{
        url: 'https://cdn.jsdelivr.net/npm/pdfjs-dist@2.0.288/cmaps/',
        isCompressed: true,
      }"
    />
  </div>
</template>

When you download CMaps files and place them in the public/cmaps directory

Composition TS

<script setup lang="ts">
import { VPdfViewer } from "@vue-pdf-viewer/viewer";

const pdfFileSource =
  "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf";
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer
      :src="pdfFileSource"
      :character-map="{
        url: '/cmaps/',
        isCompressed: true,
      }"
    />
  </div>
</template>

Composition JS

<script setup>
import { VPdfViewer } from "@vue-pdf-viewer/viewer";

const pdfFileSource =
  "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf";
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer
      :src="pdfFileSource"
      :character-map="{
        url: '/cmaps/',
        isCompressed: true,
      }"
    />
  </div>
</template>

Options TS

<script lang="ts">
import { defineComponent } from "vue";
import { VPdfViewer } from "@vue-pdf-viewer/viewer";

export default defineComponent({
  components: { VPdfViewer },
  data() {
    return {
      pdfFileSource:
        "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf",
    };
  },
});
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer
      :src="pdfFileSource"
      :character-map="{
        url: '/cmaps/',
        isCompressed: true,
      }"
    />
  </div>
</template>

Options JS

<script>
import { VPdfViewer } from "@vue-pdf-viewer/viewer";

export default {
  components: { VPdfViewer },
  data() {
    return {
      pdfFileSource:
        "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf",
    };
  },
};
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer
      :src="pdfFileSource"
      :character-map="{
        url: '/cmaps/',
        isCompressed: true,
      }"
    />
  </div>
</template>

ViewportDimensions

type	description
height	Height of the PDF page
width	Width of the PDF page
canvasHeight	Height of the canvas object
canvasWidth	Width of the canvas object
widthRatio	Ratio of the canvas width to the page width
heigthRatio	Ratio of the canvas height to the page height

Example

Composition TS

<script setup lang="ts">
  import { VPdfViewer, type CanvasLoadedCallback } from '@vue-pdf-viewer/viewer';
  const pdfFileSource = "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf";
  
  const afterCanvasLoaded: Record<number, CanvasLoadedCallback> = {
  1: (element, viewport) => {
    const context = element.getContext('2d')
    const {width, widthRatio} = viewport;
    // this code will write text "test" to the top-right of the canvas after page content is rendered
    context?.fillText('test', (width * widthRatio) - 50, 50)
  }
}
</script>
<template>
  <div :style="{ width: '1028px', height: '700px'}">
    <VPdfViewer
      :src="pdfFileSource"
      :after-canvas-loaded="afterCanvasLoaded"
    />
  </div>
</template>

Composition JS

<script setup>
  import { VPdfViewer } from '@vue-pdf-viewer/viewer';
  const pdfFileSource = "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf";
  
  const afterCanvasLoaded = {
  1: (element, viewport) => {
    const context = element.getContext('2d')
    const {width, widthRatio} = viewport;
    // this code will write text "test" to the top-right of the canvas after page content is rendered
    context?.fillText('test', (width * widthRatio) - 50, 50)
  }
}
</script>
<template>
  <div :style="{ width: '1028px', height: '700px'}">
    <VPdfViewer
      :src="pdfFileSource"
      :after-canvas-loaded="afterCanvasLoaded"
    />
  </div>
</template>

Options TS

<script lang="ts">
  import { VPdfViewer, type CanvasLoadedCallback } from '@vue-pdf-viewer/viewer';
  import { defineComponent } from 'vue'

  export default defineComponent({
    components: { VPdfViewer },
    data(): { pdfFileSource: string; afterCanvasLoaded: Record<number, CanvasLoadedCallback> } {
      return {
        pdfFileSource:
          'https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf',
        afterCanvasLoaded: {
          1: (element, viewport) => {
            const context = element.getContext('2d')
            const { width, widthRatio } = viewport
            // this code will write text "test" to the top-right of the canvas after page content is rendered
            context?.fillText('test', width * widthRatio - 50, 50)
          }
        }
      }
    }
  })
</script>
<template>
  <div :style="{ width: '1028px', height: '700px'}">
    <VPdfViewer
      :src="pdfFileSource"
      :after-canvas-loaded="afterCanvasLoaded"
    />
  </div>
</template>

Options JS

<script >
  import { VPdfViewer } from '@vue-pdf-viewer/viewer';

  export default {
    components: { VPdfViewer },
    data() {
      return {
        pdfFileSource:
          'https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf',
        afterCanvasLoaded: {
          1: (element, viewport) => {
            const context = element.getContext('2d')
            const { width, widthRatio } = viewport
            // this code will write text "test" to the top-right of the canvas after page content is rendered
            context?.fillText('test', width * widthRatio - 50, 50)
          }
        }
      }
    }
  }
</script>
<template>
  <div :style="{ width: '1028px', height: '700px'}">
    <VPdfViewer
      :src="pdfFileSource"
      :after-canvas-loaded="afterCanvasLoaded"
    />
  </div>
</template>

Localization

Currently, Vue PDF Viewer component comes with built-in translations of 5 languages, namely: The default localizations provided are:

• en_US (English - United States)
• it_IT (Italian - Italy)
• pt_PT (Portuguese - Portugal)
• th_TH (Thai - Thailand)
• zh_CN (Chinese - China)

To change the translations, VPV provide localization keys for easy customization. Each key corresponds to a specific text that will be displayed in the component for each locale.

Here are the keys you can localize:

Key	Description	Type	Default (en_US)
documentPropertiesLabel	Label of the document properties option in More Options and the title of document properties modal	string	Document properties
documentPropertiesTooltip	Tooltip text of the document properties option	string	View document properties
dragDropFileMessage	Message of the drag & drop mask when a file is dragged over the component	string	Drag and drop the PDF file here
dualPageLabel	Label of the dual page panel in More Options	string	Dual Page
firstPageLabel	Label of the first page option in More Options	string	First page
firstPageTooltip	Tooltip text of the first page option	string	Go to first page
fullScreenLabel	Label of the full screen option in More Options on mobile responsive	string	Full screen
fullScreenTooltip	Tooltip text of the full screen button and the full screen option	string	Full screen
handToolLabel	Label of the hand tool option in More options	string	Hand tool
handToolTooltip	Tooltip text of the hand tool option	string	Enable hand tool
lastPageLabel	Label of the last page option in More Options	string	Last page
lastPageTooltip	Tooltip text of the last page option	string	Go to last page
moreOptionTooltip	Tooltip text of the More Options button	string	More options
nextPageTooltip	Tooltip text of the next page button	string	Next page
openLocalFileLabel	Label of open local file option within More Options on mobile responsive	string	Open local file
openLocalFileTooltip	Tooltip text of the open local file button and open local file option	string	Open local file
pageScrollingLabel	Label of the page scrolling option in More Options	string	Page Scrolling
passwordConfirmLabel	Label of the confirm button in the password modal	string	Submit
passwordError	Error message in the password modal when the password is incorrect	string	Incorrect password
passwordModalMessage	Description message of the input password modal	string	This document is password protected. Please enter a password to open the file
passwordModalTitle	Title of the input password modal	string	Password Required
passwordPlaceholder	Input placeholder of the password modal	string	Enter password
previousPageTooltip	Tooltip text of the previous page button	string	Previous page
printCancelLabel	Label of the button to cancel printing process	string	Cancel
printLabel	Label of print option in More Options on mobile responsive	string	Print
printLoadingMessage	Loading message on the progress modal while preparing printing	string	Preparing Document
printTooltip	Tooltip text of the print button and the print option	string	Print
propertiesAuthorLabel	Label of the author in document properties modal	string	Author
propertiesCreateOnLabel	Label of the created date in document properties modal	string	Created on
propertiesCreatorLabel	Label of the creator in document properties modal	string	Creator
propertiesFilenameLabel	Label of the filename in document properties modal	string	File name
propertiesFileSizeLabel	Label of the file size in document properties modal	string	File size
propertiesKeywordLabel	Label of the keyword in document properties modal	string	Keywords
propertiesModifiedOnLabel	Label of the modified date in document properties modal	string	Modified on
propertiesPDFProducerLabel	Label of the PDF producer in document properties modal	string	PDF producer
propertiesPDFVersionLabel	Label of the PDF version in document properties modal	string	PDF version
propertiesPageCountLabel	Label of the page count in document properties modal	string	Page count
propertiesSubjectLabel	Label of the subject in document properties modal	string	Subject
propertiesTitleLabel	Label of the title in document properties modal	string	Title
rotateClockwiseLabel	Label of the rotate clockwise option in More Options	string	Rotate clockwise
rotateClockwiseTooltip	Tooltip text of the rotate clockwise option	string	Rotate clockwise
rotateCounterclockwiseLabel	Label of the rotate counterclockwise option in More Options	string	Rotate counterclockwise
rotateCounterclockwiseTooltip	Tooltip text of the rotate counterclockwise option	string	Rotate counterclockwise
searchButtonTooltip	Tooltip text of the search button	string	Search in Document
searchCloseButtonTooltip	Tooltip text of the close icon for the search popover	string	Close
searchInputPlaceholder	Placeholder of the search input	string	Enter to search
searchNextTooltip	Tooltip text of the next search match icon	string	Next match
searchPrevTooltip	Tooltip text of the previous search match icon	string	Previous match
singlePageLabel	Label of the single page panel option in More Options	string	Single Page
textSelectionLabel	Label of the text selection option in More Options	string	Text selection tool
textSelectionTooltip	Tooltip text of the text selection option	string	Enable text selection tool
themeEnableDarkTooltip	Tooltip text of the button to enable dark theme	string	Enable dark theme
themeEnableLightTooltip	Tooltip text of the button to enable light theme	string	Enable light theme
thumbnailTooltip	Tooltip text of the thumbnail button	string	Thumbnail
verticalScrollingLabel	Label of the vertical scrolling option in More Options	string	Vertical Scrolling
wrappedScrollingLabel	Label of the wrapped scrolling option in More Options	string	Wrapped Scrolling
zoomActualSize	Label of the actual zoom option of the zoom menu select	string	Actual size
zoomInTooltip	Tooltip text of the zoom in button	string	Zoom in
zoomOutTooltip	Tooltip text of the zoom out button	string	Zoom out
zoomPageFit	Label of the page fit zoom option of the zoom menu select	string	Page fit
zoomPageWidth	Label of the page width zoom option of the zoom menu select	string	Page width
zoomSelectTooltip	Tooltip text of the selector between zoom buttons	string	Select zoom level

Here is an example on how to replace the existing localization

Composition TS

<script setup lang="ts">
import { VPdfViewer, Locales } from "@vue-pdf-viewer/viewer";
const pdfFileSource =
  "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf";
const locale = ref("en_US");

const localization = {
  it_IT: Locales.it_IT,
  en_US: { ...Locales.en_US, searchButtonTooltip: "Click here to open search" },
};

const switchLanguage = () => {
  const prevLocale = locale.value;
  locale.value = prevLocale === "en_US" ? "it_IT" : "en_US";
};
</script>
<template>
  <button @click="switchLanguage">Switch Language</button>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer
      :src="pdfFileSource"
      :localization="localization"
      :locale="locale"
    />
  </div>
</template>

Composition JS

<script setup>
import { VPdfViewer, Locales } from "@vue-pdf-viewer/viewer";
const pdfFileSource =
  "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf";
const locale = ref("en_US");

const localization = {
  it_IT: Locales.it_IT,
  en_US: { ...Locales.en_US, searchButtonTooltip: "Click here to open search" },
};
const switchLanguage = () => {
  const prevLocale = locale.value;
  locale.value = prevLocale === "en_US" ? "it_IT" : "en_US";
};
</script>
<template>
  <button @click="switchLanguage">Switch Language</button>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer
      :src="pdfFileSource"
      :localization="localization"
      :locale="locale"
    />
  </div>
</template>

Options TS

<script lang="ts">
import { VPdfViewer, Locales } from "@vue-pdf-viewer/viewer";

export default {
  components: { VPdfViewer },
  data() {
    return {
      toolbarOptions: {
        searchable: false,
        pdfFileSource:
          "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf",
      },
      locale: "en_US",
      localization: {
        it_IT: Locales.it_IT,
        en_US: {
          ...Locales.en_US,
          searchButtonTooltip: "Click here to open search",
        },
      },
    };
  },
  methods: {
    switchLanguage() {
      const prevLocale = this.locale;
      this.locale = prevLocale === "en_US" ? "it_IT" : "en_US";
    },
  },
};
</script>
<template>
  <div>
    <button @click="switchLanguage">Switch Language</button>
    <div :style="{ width: '1028px', height: '700px' }">
      <VPdfViewer
        :src="pdfFileSource"
        :localization="localization"
        :locale="locale"
      />
    </div>
  </div>
</template>

Composition JS

<script setup>
import { VPdfViewer, Locales } from "@vue-pdf-viewer/viewer";

export default {
  components: { VPdfViewer },
  data() {
    return {
      toolbarOptions: {
        searchable: false,
        pdfFileSource:
          "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf",
      },
      locale: "en_US",
      localization: {
        it_IT: Locales.it_IT,
        en_US: {
          ...Locales.en_US,
          searchButtonTooltip: "Click here to open search",
        },
      },
    };
  },
  methods: {
    switchLanguage() {
      const prevLocale = this.locale;
      this.locale = prevLocale === "en_US" ? "it_IT" : "en_US";
    },
  },
};
</script>
<template>
  <div>
    <button @click="switchLanguage">Switch Language</button>
    <div :style="{ width: '1028px', height: '700px' }">
      <VPdfViewer
        :src="pdfFileSource"
        :localization="localization"
        :locale="locale"
      />
    </div>
  </div>
</template>

If you wish to add a custom language, please do so by using the locale and localization props in the component:

<VPdfViewer locale="customLang" :localization="{ customLang: { .... } }" />

It's important to note that the locale string must match the key in the localization object. Otherwise, it will fall back to en_US.

Remark: If you would like to request another built-in language, please submit a request on GitHub.

ScrollMode

The ScrollMode enumeration is used to define how pages will be scrolled in the viewer. This is configured via the initialScrollMode prop:

• ScrollMode.Horizontal: Pages are scrolled horizontally. This mode is compatible with ViewMode.SinglePage only.
• ScrollMode.Page: Displays one page at a time, enabling users to scroll through individual pages.
• ScrollMode.Vertical : Pages are scrolled vertically, displaying multiple pages stacked on top of each other.
• ScrollMode.Wrapped : Pages are wrapped, allowing multiple pages to be visible in a grid-like structure while scrolling.

ToolbarOptions

The toolbar consists of top bar and left sidebar. The tools are icons located on the Vue PDF Viewer's toolbar.

Key	Description	Type
docPropertiesEnabled	Determine whether the toolbar will show the icon of the document properties icon Remark: This icon is part of More Options icon.	boolean
downloadable	Specify whether the toolbar will show the download icon	boolean
fullscreen	Indicate whether the toolbar will show the fullscreen icon	boolean
jumpNavigatable	Determine whether the toolbar will show the first page & last page assets Remark: This icon is part of More Options icon.	boolean
pointerSwitchable	Determine whether the toolbar will show the selection mode assets Remark: This icon is part of More Options icon.	boolean
navigatable	Indicate whether the toolbar will show the navigation assets	boolean
newFileOpenable	Indicate whether the toolbar will show the icon to open local file, including the drag-and-drop zone	boolean
printable	Determine whether the toolbar will show the print icon	boolean
rotatable	Specify whether whether the toolbar will show the rotation assets Remark: This icon is part of More Options icon.	boolean
searchable	Determine whether the toolbar will show the search icon Remark: The text-layer property must be true.	boolean
sidebarEnable	Determine whether the toolbar will show the sidebar	boolean
themeSwitchable	Specify whether the toolbar will show the icon to switch theme Remark: themeSwtichable may be used together with is-dark prop and @dark-mode-changed emit event.	boolean
thumbnailViewable	Indicate whether the toolbar will show the thumbnail icon	boolean
zoomable	Specify whether the toolbar will show the zoom assets	boolean

Remark: The toolbar will show all options by default since each key's value is set to true.

docPropertiesEnabled, jumpNavigatable, pointerSwitchable and rotatable are grouped within ... icon (More Options). There are two conditions to hide More Options:

1. Set false on the 4 keys mentioned above - This will hide More Options on the desktop view;
2. Repeat step 1 and set false on downloadable, fullscreen, newFileOpenable and printable - This will hide More Options on the mobile view.

Here is an example of how to disable the search icon on the toolbar

Composition TS

<script setup lang="ts">
import { VPdfViewer, type ToolbarOptions } from "@vue-pdf-viewer/viewer";

const toolbarOptions: Partial<ToolbarOptions> = {
  searchable: false,
};
const pdfFileSource =
  "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf";
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer :src="pdfFileSource" :toolbarOptions="toolbarOptions" />
  </div>
</template>

Composition JS

<script setup>
import { VPdfViewer } from "@vue-pdf-viewer/viewer";

const toolbarOptions = {
  searchable: false,
};
const pdfFileSource =
  "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf";
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer :src="pdfFileSource" :toolbarOptions="toolbarOptions" />
  </div>
</template>

Options TS

<script lang="ts">
import { defineComponent } from "vue";
import { VPdfViewer } from "@vue-pdf-viewer/viewer";

export default defineComponent({
  components: { VPdfViewer },
  data() {
    return {
      toolbarOptions: { searchable: false },
      pdfFileSource:
        "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf",
    };
  },
});
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer :src="pdfFileSource" :toolbarOptions="toolbarOptions" />
  </div>
</template>

Options JS

<script>
import { VPdfViewer } from "@vue-pdf-viewer/viewer";

export default {
  components: { VPdfViewer },
  data() {
    return {
      toolbarOptions: {
        searchable: false,
        pdfFileSource:
          "https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf",
      },
    };
  },
};
</script>
<template>
  <div :style="{ width: '1028px', height: '700px' }">
    <VPdfViewer :src="pdfFileSource" :toolbarOptions="toolbarOptions" />
  </div>
</template>

ViewMode

The ViewMode enumeration defines how pages are visually laid out in the viewer. This is configured using the initialViewMode prop:

• ViewMode.SinglePage: Displays a single page in each row, making it easy to focus on one page at a time.
• ViewMode.DualPage: Displays two pages side-by-side, ideal for viewing documents that are meant to be read in pairs.

ZoomLevel

The ZoomLevel enumeration defines how pages will be scaled in the viewer. This is configured via the initialScale prop:

• ZoomLevel.ActualSize: Pages are rendered at their actual PDF size.
• ZoomLevel.PageFit: Pages are scaled to fit within the viewer's width and height.
• ZoomLevel.PageWidth: Pages are scaled to fit the viewer's width.