Skip to content

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.

functiondescription
(canvasElement: HTMLCanvasElement, viewport: ViewportDimensions) => voidCallback function to call after the canvas element is rendered

CharacterMap

KeyDescriptionType
urlThe URL or relative path where the predefined Adobe CMaps are located. It must have / at the end.string
isCompressedSpecify if the Adobe CMaps are binary packed. The default value is true.boolean
vue
<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>
vue
<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>
vue
<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>
vue
<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

vue
<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>
vue
<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>
vue
<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>
vue
<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

typedescription
heightHeight of the PDF page
widthWidth of the PDF page
canvasHeightHeight of the canvas object
canvasWidthWidth of the canvas object
widthRatioRatio of the canvas width to the page width
heigthRatioRatio of the canvas height to the page height

Example

vue
<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>
vue
<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>
vue
<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>
vue
<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:

KeyDescriptionTypeDefault (en_US)
documentPropertiesLabelLabel of the document properties option in More Options and the title of document properties modalstringDocument properties
documentPropertiesTooltipTooltip text of the document properties optionstringView document properties
dragDropFileMessageMessage of the drag & drop mask when a file is dragged over the componentstringDrag and drop the PDF file here
dualPageLabelLabel of the dual page panel in More OptionsstringDual Page
firstPageLabelLabel of the first page option in More OptionsstringFirst page
firstPageTooltipTooltip text of the first page optionstringGo to first page
fullScreenLabelLabel of the full screen option in More Options on mobile responsivestringFull screen
fullScreenTooltipTooltip text of the full screen button and the full screen optionstringFull screen
handToolLabelLabel of the hand tool option in More optionsstringHand tool
handToolTooltipTooltip text of the hand tool optionstringEnable hand tool
lastPageLabelLabel of the last page option in More OptionsstringLast page
lastPageTooltipTooltip text of the last page optionstringGo to last page
moreOptionTooltipTooltip text of the More Options buttonstringMore options
nextPageTooltipTooltip text of the next page buttonstringNext page
openLocalFileLabelLabel of open local file option within More Options on mobile responsivestringOpen local file
openLocalFileTooltipTooltip text of the open local file button and open local file optionstringOpen local file
pageScrollingLabelLabel of the page scrolling option in More OptionsstringPage Scrolling
passwordConfirmLabelLabel of the confirm button in the password modalstringSubmit
passwordErrorError message in the password modal when the password is incorrectstringIncorrect password
passwordModalMessageDescription message of the input password modalstringThis document is password protected. Please enter a password to open the file
passwordModalTitleTitle of the input password modalstringPassword Required
passwordPlaceholderInput placeholder of the password modalstringEnter password
previousPageTooltipTooltip text of the previous page buttonstringPrevious page
printCancelLabelLabel of the button to cancel printing processstringCancel
printLabelLabel of print option in More Options on mobile responsivestringPrint
printLoadingMessageLoading message on the progress modal while preparing printingstringPreparing Document
printTooltipTooltip text of the print button and the print optionstringPrint
propertiesAuthorLabelLabel of the author in document properties modalstringAuthor
propertiesCreateOnLabelLabel of the created date in document properties modalstringCreated on
propertiesCreatorLabelLabel of the creator in document properties modalstringCreator
propertiesFilenameLabelLabel of the filename in document properties modalstringFile name
propertiesFileSizeLabelLabel of the file size in document properties modalstringFile size
propertiesKeywordLabelLabel of the keyword in document properties modalstringKeywords
propertiesModifiedOnLabelLabel of the modified date in document properties modalstringModified on
propertiesPDFProducerLabelLabel of the PDF producer in document properties modalstringPDF producer
propertiesPDFVersionLabelLabel of the PDF version in document properties modalstringPDF version
propertiesPageCountLabelLabel of the page count in document properties modalstringPage count
propertiesSubjectLabelLabel of the subject in document properties modalstringSubject
propertiesTitleLabelLabel of the title in document properties modalstringTitle
rotateClockwiseLabelLabel of the rotate clockwise option in More OptionsstringRotate clockwise
rotateClockwiseTooltipTooltip text of the rotate clockwise optionstringRotate clockwise
rotateCounterclockwiseLabelLabel of the rotate counterclockwise option in More OptionsstringRotate counterclockwise
rotateCounterclockwiseTooltipTooltip text of the rotate counterclockwise optionstringRotate counterclockwise
searchButtonTooltipTooltip text of the search buttonstringSearch in Document
searchCloseButtonTooltipTooltip text of the close icon for the search popoverstringClose
searchInputPlaceholderPlaceholder of the search inputstringEnter to search
searchNextTooltipTooltip text of the next search match iconstringNext match
searchPrevTooltipTooltip text of the previous search match iconstringPrevious match
singlePageLabelLabel of the single page panel option in More OptionsstringSingle Page
textSelectionLabelLabel of the text selection option in More OptionsstringText selection tool
textSelectionTooltipTooltip text of the text selection optionstringEnable text selection tool
themeEnableDarkTooltipTooltip text of the button to enable dark themestringEnable dark theme
themeEnableLightTooltipTooltip text of the button to enable light themestringEnable light theme
thumbnailTooltipTooltip text of the thumbnail buttonstringThumbnail
verticalScrollingLabelLabel of the vertical scrolling option in More OptionsstringVertical Scrolling
wrappedScrollingLabelLabel of the wrapped scrolling option in More OptionsstringWrapped Scrolling
zoomActualSizeLabel of the actual zoom option of the zoom menu selectstringActual size
zoomInTooltipTooltip text of the zoom in buttonstringZoom in
zoomOutTooltipTooltip text of the zoom out buttonstringZoom out
zoomPageFitLabel of the page fit zoom option of the zoom menu selectstringPage fit
zoomPageWidthLabel of the page width zoom option of the zoom menu selectstringPage width
zoomSelectTooltipTooltip text of the selector between zoom buttonsstringSelect zoom level

Here is an example on how to replace the existing localization

vue
<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>
vue
<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>
vue
<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>
vue
<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:

html
<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.

KeyDescriptionType
docPropertiesEnabledDetermine whether the toolbar will show the icon of the document properties icon
Remark: This icon is part of More Options icon.
boolean
downloadableSpecify whether the toolbar will show the download iconboolean
fullscreenIndicate whether the toolbar will show the fullscreen iconboolean
jumpNavigatableDetermine whether the toolbar will show the first page & last page assets
Remark: This icon is part of More Options icon.
boolean
pointerSwitchableDetermine whether the toolbar will show the selection mode assets
Remark: This icon is part of More Options icon.
boolean
navigatableIndicate whether the toolbar will show the navigation assetsboolean
newFileOpenableIndicate whether the toolbar will show the icon to open local file, including the drag-and-drop zoneboolean
printableDetermine whether the toolbar will show the print iconboolean
rotatableSpecify whether whether the toolbar will show the rotation assets
Remark: This icon is part of More Options icon.
boolean
searchableDetermine whether the toolbar will show the search icon
Remark: The text-layer property must be true.
boolean
sidebarEnableDetermine whether the toolbar will show the sidebarboolean
themeSwitchableSpecify 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
thumbnailViewableIndicate whether the toolbar will show the thumbnail iconboolean
zoomableSpecify whether the toolbar will show the zoom assetsboolean

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

vue
<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>
vue
<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>
vue
<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>
vue
<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.