# Highlights

Draw and navigate to rectangles in page coordinates.

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

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.

`HighlightLayer` draws the rectangles in `usePdf((state) => state.highlights)`. Use it for search results, citation targets, or a selected region. It does not extract text, save data, or write annotations into the PDF.

## Show a region and scroll to it

Complete [installation](https://anara.com/lector/docs/installation) first. The rectangle below is an illustrative region on page 1; replace it with coordinates from your document.

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

import {
  CanvasLayer, HighlightLayer, Page, Pages, Root, TextLayer,
  usePdf, usePdfJump, type HighlightRect,
} from "@anaralabs/lector";
import "./pdf-setup";

const region: HighlightRect[] = [
  { pageNumber: 1, left: 10, top: 15, width: 70, height: 5, type: "percent" },
];

function HighlightControls() {
  const { jumpToHighlightRects } = usePdfJump();
  const setHighlight = usePdf((state) => state.setHighlight);

  return (
    <div>
      <button type="button" onClick={() => jumpToHighlightRects(region, "percent", "center")}>
        Show region
      </button>
      <button type="button" onClick={() => setHighlight([])}>Clear highlight</button>
    </div>
  );
}

export default function HighlightViewer() {
  return (
    <Root source="/sample.pdf" style={{ height: 600, display: "flex", flexDirection: "column" }}>
      <HighlightControls />
      <div style={{ flex: 1, minHeight: 0 }}>
        <Pages>
          <Page>
            <CanvasLayer />
            <TextLayer />
            <HighlightLayer style={{ background: "#ffdf6080" }} />
          </Page>
        </Pages>
      </div>
    </Root>
  );
}
```

To draw without scrolling, call `setHighlight(rects)`. It **replaces** the active rectangles. To scroll without replacing them, use `scrollToHighlightRects` from `usePdfJump`.

## Coordinate contract

| Field             | Meaning                                                      |
| ----------------- | ------------------------------------------------------------ |
| `pageNumber`      | One-based page number                                        |
| `left`, `top`     | Distance from the page's top-left corner                     |
| `width`, `height` | Rectangle size in the same units                             |
| `type`            | `"pixels"` (also used when omitted) or `"percent"`           |
| `style`           | Optional function from the rectangle to React CSS properties |

Pixel coordinates use the page's scale-1 viewport, not screen pixels or raw PDF bottom-left coordinates. Selection and search helpers return this format. For percentage coordinates, `10` means 10%, not `0.1`.

Set `type: "percent"` on **each rectangle** and also pass `"percent"` to the jump helper. The rectangle controls drawing; the helper argument controls scrolling. Mixing the units makes the viewport and overlay disagree.

For coordinates from a backend PDF parser, account for the PDF crop box, rotation, and origin before drawing. You can obtain the page through `getPdfPageProxy(pageNumber)` and use PDF.js viewport conversion methods.

## Styling and persistence

The layer supplies positioning and `pointer-events: none`; give it a background color or border so it is visible. Props and styles apply to every rectangle. Avoid opaque fills that hide the text.

Save serializable rectangle data with a document ID and revision if it must survive a reload. A `style` callback is not serializable; reconstruct styling in your app. Changing the source or unmounting `Root` creates a new viewer state. See [selection](https://anara.com/lector/docs/code/select) for capturing text and coordinates and [dark mode](https://anara.com/lector/docs/dark-mode) for overlay colors.

## Live example

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