Text Selection Controller viewer>=4.2.0 & annotation>=1.5.0

AnnotationTextSelectionControl

An instance object that allows programmatic control of text selection annotation tools (highlight, underline, strikethrough). It requires the @vue-pdf-viewer/annotation@^1.5.0 plugin to be loaded. A console warning is shown if methods are called without it.

Plugin Required

annotationTextSelectionControl is undefined when the annotation plugin is not passed to the Vue PDF component. Always use optional chaining: viewerRef.value?.annotationTextSelectionControl?.toggleHighlight().

Reactive State

Name	Description	Type
`isHighlightActive`	Whether the highlight tool is currently active	`boolean`
`isUnderlineActive`	Whether the underline tool is currently active	`boolean`
`isStrikethroughActive`	Whether the strikethrough tool is currently active	`boolean`
`highlightColor`	Current highlight color as CSS hex string, or `null` if not set	`string \| null`
`underlineColor`	Current underline color as CSS hex string, or `null` if not set	`string \| null`
`strikethroughColor`	Current strikethrough color as CSS hex string, or `null` if not set	`string \| null`

Tool Activation Methods

Name	Description	Type
`toggleHighlight`	Toggle highlight tool on/off. Activating deactivates other text selection tools.	`() => void`
`toggleUnderline`	Toggle underline tool on/off. Activating deactivates other text selection tools.	`() => void`
`toggleStrikethrough`	Toggle strikethrough tool on/off. Activating deactivates other text selection tools.	`() => void`
`deactivateAll`	Deactivate all text selection tools.	`() => void`

Color Methods

Name	Description	Type
`setHighlightColor`	Set highlight color. Takes effect on the next annotation created.	`(color: string) => void`
`setUnderlineColor`	Set underline color. Takes effect on the next annotation created.	`(color: string) => void`
`setStrikethroughColor`	Set strikethrough color. Takes effect on the next annotation created.	`(color: string) => void`

Color Palette Methods

These methods set the color palette shown in the post-selection popover. Useful when the annotation plugin is configured with a tool disabled (e.g., highlight: false) but you still want to use that tool via the instance API.

Name	Description	Type
`setHighlightColorPalette`	Set the highlight color palette for the popover. Also sets the current color to the first entry if not already set.	`(colors: AnnotationHighlightColors) => void`
`setUnderlineColorPalette`	Set the underline color palette for the popover. Also sets the current color to the first entry if not already set.	`(colors: AnnotationUnderlineColors) => void`
`setStrikethroughColorPalette`	Set the strikethrough color palette for the popover. Also sets the current color to the first entry if not already set.	`(colors: AnnotationStrikethroughColors) => void`

The colors parameter accepts the same type as the plugin options — either a string[] of CSS hex colors or a LabelValuePair[] with { value, label } entries (1–12 items).

typescript

// Use string[]
annotationTextSelectionControl.setHighlightColorPalette([
  '#FF0000', '#00FF00', '#0000FF', '#FFFF00', '#FF00FF', '#00FFFF'
])

// Use LabelValuePair[]
annotationTextSelectionControl.setHighlightColorPalette([
  { value: '#CAAAFF', label: 'Purple' },
  { value: '#65EDE9', label: 'Cyan' },
  { value: '#FFACAC', label: 'Red' },
  { value: '#FFBD82', label: 'Orange' },
  { value: '#FCE244', label: 'Yellow' },
  { value: '#A0F751', label: 'Green' },
])

Mutual Exclusivity

Only one text selection tool can be active at a time. Activating a tool via toggleHighlight(), toggleUnderline(), or toggleStrikethrough() automatically deactivates the others.

API Independence from Plugin Config

The instance API operates independently from the annotation plugin configuration. You can disable a tool in the plugin options (which hides it from the built-in toolbar) and still activate it via the API:

typescript

// Plugin config: Highlight is disabled in the toolbar
const annotationPlugin = VPdfAnnotationPlugin({
  textSelection: {
    highlight: false, // Hide the highlight button from the built-in toolbar
    underline: true,
    strikethrough: true,
  }
})

// API: Highlight still works programmatically
viewerRef.value?.annotationTextSelectionControl?.setHighlightColorPalette([
  '#FF0000', '#00FF00', '#0000FF', '#FFFF00', '#FF00FF', '#00FFFF'
])
viewerRef.value?.annotationTextSelectionControl?.toggleHighlight()

Bidirectional Sync

annotationTextSelectionControl properties are reactive. When a user activates or deactivates a text selection tool via the built-in annotation toolbar, isHighlightActive, isUnderlineActive, and isStrikethroughActive update reactively.

Example

Composition TSComposition JSOptions TSOptions JS

vue

<script setup lang="ts">
import { VPdfViewer, type VPVInstance } from '@vue-pdf-viewer/viewer'
import VPdfAnnotationPlugin from '@vue-pdf-viewer/annotation'
import { ref, computed } from 'vue'

const viewerRef = ref<VPVInstance>()
const annotationTextSelectionControl = computed(() => viewerRef.value?.annotationTextSelectionControl)

const annotationPlugin = VPdfAnnotationPlugin({
  // Hide the text-selection annotation button of the toolbar
  textSelection: false
})

const toggleHighlight = () => {
  annotationTextSelectionControl.value?.toggleHighlight()
}

const toggleUnderline = () => {
  annotationTextSelectionControl.value?.toggleUnderline()
}

const toggleStrikethrough = () => {
  annotationTextSelectionControl.value?.toggleStrikethrough()
}

const changeTextSelectionAnnotationColor = (color: string) => {
  annotationTextSelectionControl.value?.setHighlightColor(color)
  annotationTextSelectionControl.value?.setUnderlineColor(color)
  annotationTextSelectionControl.value?.setStrikethroughColor(color)
}

const deactivateAll = () => {
  annotationTextSelectionControl.value?.deactivateAll()
}
</script>
<template>
  <div id="vpv">
    <div class="custom-toolbar">
      <button
        :class="{ active: annotationTextSelectionControl?.isHighlightActive }"
        @click="toggleHighlight"
      >
        Highlight
      </button>
      <button
        :class="{ active: annotationTextSelectionControl?.isUnderlineActive }"
        @click="toggleUnderline"
      >
        Underline
      </button>
      <button
        :class="{ active: annotationTextSelectionControl?.isStrikethroughActive }"
        @click="toggleStrikethrough"
      >
        Strikethrough
      </button>
      <button @click="deactivateAll">Deactivate All</button>
      <button @click="changeTextSelectionAnnotationColor('#FF0000')">Annotate in Red</button>
    </div>
    <div :style="{ width: '100%', height: '100%' }">
      <VPdfViewer
        ref="viewerRef"
        src="https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf"
        :plugins="[annotationPlugin]"
      />
    </div>
  </div>
</template>
<style scoped>
#vpv {
  width: 100%;
  height: 1490px;
  margin: 0 auto;
}
@media (max-width: 992px) {
  #vpv {
    width: 85%;
  }
}
@media (max-width: 1028px) {
  #vpv {
    width: 70%;
  }
}
.custom-toolbar button.active {
  background-color: #e0e0ff;
  font-weight: bold;
}
</style>

vue

<script setup>
import { VPdfViewer } from '@vue-pdf-viewer/viewer'
import VPdfAnnotationPlugin from '@vue-pdf-viewer/annotation'
import { ref, computed } from 'vue'

const viewerRef = ref()
const annotationTextSelectionControl = computed(() => viewerRef.value?.annotationTextSelectionControl)

const annotationPlugin = VPdfAnnotationPlugin({
  // Hide the text-selection annotation button of the toolbar
  textSelection: false
})

const toggleHighlight = () => {
  annotationTextSelectionControl.value?.toggleHighlight()
}

const toggleUnderline = () => {
  annotationTextSelectionControl.value?.toggleUnderline()
}

const toggleStrikethrough = () => {
  annotationTextSelectionControl.value?.toggleStrikethrough()
}

const changeTextSelectionAnnotationColor = (color) => {
  annotationTextSelectionControl.value?.setHighlightColor(color)
  annotationTextSelectionControl.value?.setUnderlineColor(color)
  annotationTextSelectionControl.value?.setStrikethroughColor(color)
}

const deactivateAll = () => {
  annotationTextSelectionControl.value?.deactivateAll()
}
</script>
<template>
  <div id="vpv">
    <div class="custom-toolbar">
      <button
        :class="{ active: annotationTextSelectionControl?.isHighlightActive }"
        @click="toggleHighlight"
      >
        Highlight
      </button>
      <button
        :class="{ active: annotationTextSelectionControl?.isUnderlineActive }"
        @click="toggleUnderline"
      >
        Underline
      </button>
      <button
        :class="{ active: annotationTextSelectionControl?.isStrikethroughActive }"
        @click="toggleStrikethrough"
      >
        Strikethrough
      </button>
      <button @click="deactivateAll">Deactivate All</button>
      <button @click="changeTextSelectionAnnotationColor('#FF0000')">Annotate in Red</button>
    </div>
    <div :style="{ width: '100%', height: '100%' }">
      <VPdfViewer
        ref="viewerRef"
        src="https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf"
        :plugins="[annotationPlugin]"
      />
    </div>
  </div>
</template>
<style scoped>
#vpv {
  width: 100%;
  height: 1490px;
  margin: 0 auto;
}
@media (max-width: 992px) {
  #vpv {
    width: 85%;
  }
}
@media (max-width: 1028px) {
  #vpv {
    width: 70%;
  }
}
.custom-toolbar button.active {
  background-color: #e0e0ff;
  font-weight: bold;
}
</style>

vue

<script lang="ts">
import { VPdfViewer, type VPVInstance } from '@vue-pdf-viewer/viewer'
import VPdfAnnotationPlugin from '@vue-pdf-viewer/annotation'
import { ref, computed, defineComponent } from 'vue'

export default defineComponent({
  components: { VPdfViewer },
  setup() {
    const viewerRef = ref<VPVInstance>()
    const annotationTextSelectionControl = computed(() => viewerRef.value?.annotationTextSelectionControl)

    const annotationPlugin = VPdfAnnotationPlugin({
      // Hide the text-selection annotation button of the toolbar
      textSelection: false
    })

    const toggleHighlight = () => annotationTextSelectionControl.value?.toggleHighlight()
    const toggleUnderline = () => annotationTextSelectionControl.value?.toggleUnderline()
    const toggleStrikethrough = () => annotationTextSelectionControl.value?.toggleStrikethrough()
    const changeTextSelectionAnnotationColor = (color: string) => {
      annotationTextSelectionControl.value?.setHighlightColor(color)
      annotationTextSelectionControl.value?.setUnderlineColor(color)
      annotationTextSelectionControl.value?.setStrikethroughColor(color)
    }

    const deactivateAll = () => annotationTextSelectionControl.value?.deactivateAll()

    return {
      viewerRef,
      annotationPlugin,
      annotationTextSelectionControl,
      toggleHighlight,
      toggleUnderline,
      toggleStrikethrough,
      changeTextSelectionAnnotationColor,
      deactivateAll,
    }
  }
})
</script>

<template>
  <div id="vpv">
    <div class="custom-toolbar">
      <button
        :class="{ active: annotationTextSelectionControl?.isHighlightActive }"
        @click="toggleHighlight"
      >
        Highlight
      </button>
      <button
        :class="{ active: annotationTextSelectionControl?.isUnderlineActive }"
        @click="toggleUnderline"
      >
        Underline
      </button>
      <button
        :class="{ active: annotationTextSelectionControl?.isStrikethroughActive }"
        @click="toggleStrikethrough"
      >
        Strikethrough
      </button>
      <button @click="deactivateAll">Deactivate All</button>
      <button @click="changeTextSelectionAnnotationColor('#FF0000')">Annotate in Red</button>
    </div>
    <div :style="{ width: '100%', height: '100%' }">
      <VPdfViewer
        ref="viewerRef"
        src="https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf"
        :plugins="[annotationPlugin]"
      />
    </div>
  </div>
</template>
<style scoped>
#vpv {
  width: 100%;
  height: 1490px;
  margin: 0 auto;
}
@media (max-width: 992px) {
  #vpv {
    width: 85%;
  }
}
@media (max-width: 1028px) {
  #vpv {
    width: 70%;
  }
}
.custom-toolbar button.active {
  background-color: #e0e0ff;
  font-weight: bold;
}
</style>

vue

<script>
import { VPdfViewer } from '@vue-pdf-viewer/viewer'
import VPdfAnnotationPlugin from '@vue-pdf-viewer/annotation'
import { ref, computed, defineComponent } from 'vue'

export default defineComponent({
  components: { VPdfViewer },
  setup() {
    const viewerRef = ref()
    const annotationTextSelectionControl = computed(() => viewerRef.value?.annotationTextSelectionControl)

    const annotationPlugin = VPdfAnnotationPlugin({
      // Hide the text-selection annotation button of the toolbar
      textSelection: false
    })

    const toggleHighlight = () => annotationTextSelectionControl.value?.toggleHighlight()
    const toggleUnderline = () => annotationTextSelectionControl.value?.toggleUnderline()
    const toggleStrikethrough = () => annotationTextSelectionControl.value?.toggleStrikethrough()
    const changeTextSelectionAnnotationColor = (color) => {
      annotationTextSelectionControl.value?.setHighlightColor(color)
      annotationTextSelectionControl.value?.setUnderlineColor(color)
      annotationTextSelectionControl.value?.setStrikethroughColor(color)
    }
    const deactivateAll = () => annotationTextSelectionControl.value?.deactivateAll()

    return {
      viewerRef,
      annotationPlugin,
      annotationTextSelectionControl,
      toggleHighlight,
      toggleUnderline,
      toggleStrikethrough,
      changeTextSelectionAnnotationColor,
      deactivateAll,
    }
  }
})
</script>

<template>
  <div id="vpv">
    <div class="custom-toolbar">
      <button
        :class="{ active: annotationTextSelectionControl?.isHighlightActive }"
        @click="toggleHighlight"
      >
        Highlight
      </button>
      <button
        :class="{ active: annotationTextSelectionControl?.isUnderlineActive }"
        @click="toggleUnderline"
      >
        Underline
      </button>
      <button
        :class="{ active: annotationTextSelectionControl?.isStrikethroughActive }"
        @click="toggleStrikethrough"
      >
        Strikethrough
      </button>
      <button @click="deactivateAll">Deactivate All</button>
      <button @click="changeTextSelectionAnnotationColor('#FF0000')">Annotate in Red</button>
    </div>
    <div :style="{ width: '100%', height: '100%' }">
      <VPdfViewer
        ref="viewerRef"
        src="https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf"
        :plugins="[annotationPlugin]"
      />
    </div>
  </div>
</template>
<style scoped>
#vpv {
  width: 100%;
  height: 1490px;
  margin: 0 auto;
}
@media (max-width: 992px) {
  #vpv {
    width: 85%;
  }
}
@media (max-width: 1028px) {
  #vpv {
    width: 70%;
  }
}
.custom-toolbar button.active {
  background-color: #e0e0ff;
  font-weight: bold;
}
</style>

Events

Slots

Slots - Tools

Text Selection Controller viewer>=4.2.0 & annotation>=1.5.0

AnnotationTextSelectionControl

Reactive State

Tool Activation Methods

Color Methods

Color Palette Methods

Mutual Exclusivity

API Independence from Plugin Config

Bidirectional Sync

Example

Slots - Tools

Text Selection Controller viewer>=4.2.0 & annotation>=1.5.0 ​

AnnotationTextSelectionControl ​

Reactive State ​

Tool Activation Methods ​

Color Methods ​

Color Palette Methods ​

Mutual Exclusivity ​

API Independence from Plugin Config ​

Bidirectional Sync ​

Example ​

Text Selection Controller viewer>=4.2.0 & annotation>=1.5.0

AnnotationTextSelectionControl

Reactive State

Tool Activation Methods

Color Methods

Color Palette Methods

Mutual Exclusivity

API Independence from Plugin Config

Bidirectional Sync

Example