Selection Plugin

The Selection Plugin enables users to select text within the PDF document, just like on a standard webpage. It provides the <SelectionLayer /> to visually highlight the selected text and a rich API to get the selected content.

Installation

This plugin depends on the Interaction Manager plugin. You must install both packages.


npm install @embedpdf/plugin-selection @embedpdf/plugin-interaction-manager


pnpm add @embedpdf/plugin-selection @embedpdf/plugin-interaction-manager


yarn add @embedpdf/plugin-selection @embedpdf/plugin-interaction-manager


bun add @embedpdf/plugin-selection @embedpdf/plugin-interaction-manager

Registration

Import SelectionPluginPackage and its InteractionManager dependency, and add them to the plugins array. The Selection plugin should be registered after its dependency.


import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/vue'
import { SelectionPluginPackage } from '@embedpdf/plugin-selection/vue'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
 
  // Register dependency first
  createPluginRegistration(InteractionManagerPluginPackage),
 
  // Register the selection plugin
  createPluginRegistration(SelectionPluginPackage),
]

Usage

The plugin has two main parts: the <SelectionLayer /> component for the UI, and the useSelectionCapability composable for interacting with the selection data.

1. Displaying the Selection

To show the highlighted text, place the <SelectionLayer /> component inside the default slot of your <Scroller />. For text selection to work correctly, it must be a child of the PagePointerProvider.


<script setup lang="ts">
import { PagePointerProvider } from '@embedpdf/plugin-interaction-manager/vue';
import { SelectionLayer } from '@embedpdf/plugin-selection/vue';
</script>
<template>
  <Scroller>
    <template #default="{ page }">
      <PagePointerProvider
        :page-index="page.pageIndex"
        :page-width="page.width"
        :page-height="page.height"
        :rotation="page.rotation"
        :scale="page.scale"
      >
        <RenderLayer :page-index="page.pageIndex" :scale="page.scale" />
        <SelectionLayer :page-index="page.pageIndex" :scale="page.scale" />
      </PagePointerProvider>
    </template>
  </Scroller>
</template>

2. Interacting with the Selection

The useSelectionCapability composable allows you to work with the selected text. You can create a toolbar to copy the text or perform other actions. The plugin automatically handles the clipboard logic when you call provides.value.copyToClipboard().

You can use the onSelectionChange event to know when a selection exists, which is useful for enabling or disabling UI elements like a “Copy” button.


<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { useSelectionCapability, type SelectionRangeX } from '@embedpdf/plugin-selection/vue';
 
const { provides: selection } = useSelectionCapability();
const hasSelection = ref(false);
let unsubscribe: (() => void) | undefined;
 
onMounted(() => {
  if (!selection.value) return;
  unsubscribe = selection.value.onSelectionChange((sel: SelectionRangeX | null) => {
    hasSelection.value = !!sel;
  });
});
 
onUnmounted(() => {
  unsubscribe?.();
});
</script>
 
<template>
  <button @click="selection?.copyToClipboard()" :disabled="!hasSelection">Copy</button>
</template>

Live Example

Try selecting text in the viewer below. A “Copy Text” button will become active, allowing you to copy the selected content to your clipboard.

API Reference

Component: `<SelectionLayer />`

The component that renders the blue rectangles over the selected text.

Prop	Type	Description
`pageIndex`	`number`	(Required) The index of the page this layer is on.
`scale`	`number`	(Required) The current scale of the page.
`background`	`string`	(Optional) The color of the selection highlight. Default: `'rgba(33,150,243)'`

Composable: `useSelectionCapability()`

Connects your component to the selection plugin’s state and functions.

Returns

Property	Type	Description
`provides`	`Ref<SelectionCapability \| null>`	A ref object with methods to interact with the selection, or `null` if the plugin is not ready.

`SelectionCapability` Methods

Method	Description
`copyToClipboard()`	Triggers the process to copy the currently selected text to the user’s clipboard.
`getSelectedText()`	Returns a `Task<string[]>` that resolves with the selected text content. Each string in the array is a line.
`getFormattedSelection()`	Returns an array of objects describing the selection on each page, including its bounding box and the individual highlight rectangles.
`onSelectionChange(cb)`	Subscribes to when the text selection is created, updated, or cleared. Returns an `unsubscribe` function.
`onEndSelection(cb)`	Subscribes to when the user finishes selecting text (on mouse up). This is ideal for fetching the selected text content. Returns an `unsubscribe` function.