# PDF links

Enable existing PDF links and choose external-link and navigation behavior.

Source: https://anara.com/lector/docs/code/links

These docs describe the source deployed with this site, tracking main rather than a versioned npm release. Check your installed @anaralabs/lector and pdfjs-dist versions before applying examples.

`AnnotationLayer` renders annotations already present in the PDF, including links and form widgets. It needs the PDF.js stylesheet from [installation](https://anara.com/lector/docs/installation). It does not turn arbitrary text URLs into links.

## Enable links

```tsx title="linked-viewer.tsx"
"use client";

import { AnnotationLayer, CanvasLayer, Page, Pages, Root, TextLayer } from "@anaralabs/lector";
import "./pdf-setup";

export default function LinkedViewer() {
  return (
    <Root source="/sample.pdf" style={{ height: 600 }}>
      <Pages>
        <Page>
          <CanvasLayer />
          <TextLayer />
          <AnnotationLayer
            renderForms={false}
            externalLinksEnabled
            jumpOptions={{ behavior: "auto", align: "start" }}
          />
        </Page>
      </Pages>
    </Root>
  );
}
```

## Options

| Prop                   | Default    | Behavior                                         |
| ---------------------- | ---------- | ------------------------------------------------ |
| `externalLinksEnabled` | `true`     | Enables links to external URLs                   |
| `renderForms`          | `true`     | Renders interactive form fields as well as links |
| `jumpOptions.behavior` | `"smooth"` | `"smooth"` or `"auto"` for internal navigation   |
| `jumpOptions.align`    | `"start"`  | `"start"`, `"center"`, or `"end"`                |

Internal links navigate within the current document. When a destination includes a position, Lector can scroll to that position within the page. External links use the link service and open in a new tab by default. Set `externalLinksEnabled={false}` when your viewer should disable them.

Keep these settings consistent across page layers in a viewer: they share one link service.

## Custom navigation

For ordinary page buttons, use [usePdfJump](https://anara.com/lector/docs/code/page-navigation). For PDF-specific destinations, `usePDFLinkService()` exposes the underlying service, including `goToDestination(name)` and `page`. Destination navigation depends on the viewer scroll integration established by `AnnotationLayer`; a bare service without that integration is not a substitute for `usePdfJump`.

## Styling links

You can target the PDF.js annotation classes in your application's stylesheet:

```css
.annotationLayer .linkAnnotation > a:hover {
  background: rgb(255 220 80 / 20%);
}

.annotationLayer .linkAnnotation > a:focus-visible {
  outline: 2px solid currentColor;
}
```

If a link does nothing, first confirm the file contains an actual PDF link annotation. Then check that `AnnotationLayer` is mounted, external links are enabled if needed, and an overlay is not intercepting pointer events. See [PDF forms](https://anara.com/lector/docs/code/pdf-form) to save filled form fields.

## Live example

Open the documentation page linked above to use this interactive example.