@antoine1003/ng-file-annotator
v22.0.0
Published
Angular library for annotating images and multi-page PDFs with interactive markers and customizable popups.
Downloads
276
Readme
File Comment Lib 📄✍️
A modern, robust Angular 22 library for annotating Images and multi-page PDFs natively.
Built for enterprise applications, this library bypasses traditional <iframe> limitations by rendering PDFs natively using pdfjs-dist on HTML <canvas>. It provides highly accurate, responsive percentage-based coordinates, custom Angular CDK popovers, seamless continuous scrolling, and programmatic viewport control.
✨ Features
- Native PDF Rendering: Zero
<iframe>restrictions. Uses Mozilla's officialpdf.jsfor crisp, accurate rendering. - Multi-Page Support: Continuously scrollable PDFs where annotations stay glued to their exact page coordinates.
- Smart Positioning: Uses Angular CDK Overlay for popovers, ensuring your custom annotation forms snap perfectly to the marker without overflowing the screen.
- Programmatic Control & Highlighting: Trigger smooth scrolling to specific markers from anywhere in your app, complete with a customizable highlight/sonar pulse effect.
- Read-Only Mode: Easily lock the document to prevent new annotations while still allowing users to view existing ones.
- Zero-Config Web Workers: The PDF.js worker is bundled automatically using modern ES modules.
- 100% Customizable UI: Provide your own
ng-templatefor markers, creation forms, and view popovers.
📦 Installation
From npm registry
Install the package from the npm registry:
npm install ng-file-annotatorLocal Development (tarball)
To test the library locally without publishing, follow these steps:
1. Build the Library
ng build ng-file-annotator2. Pack into a Tarball
cd dist/ng-file-annotator
npm packThis generates a file like ng-file-annotator-22.0.0.tgz.
3. Install in your Consuming Application
npm install /path/to/your/workspace/dist/ng-file-annotator/ng-file-annotator-22.0.0.tgzNote: Because
pdfjs-distis listed in the library'sdependencies, npm will automatically fetch and install the correct version of PDF.js for your consuming app.
Deploy a New Version
- When code is ready, commit everything and bump the version in
projects/ng-file-annotator/package.json. - Build the library:
ng build ng-file-annotator - Pack it:
cd dist/ng-file-annotator npm pack - Publish the package to your npm registry.
- Drag and drop
dist/ng-file-annotator/ng-file-annotator-X.X.X.tgz.
🚀 Quick Start Usage
1. Import the Component
In your standalone component, import the annotator:
import { FileAnnotatorComponent } from 'ng-file-annotator';
import { FileItem, Annotation } from 'ng-file-annotator';
@Component({
selector: 'app-root',
imports: [FileAnnotatorComponent],
templateUrl: './app.component.html'
})
export class AppComponent {
// Setup your file (Image or PDF)
currentFile = signal<FileItem>({
id: '123',
type: 'pdf',
name: 'document.pdf',
url: 'blob:http://...',
isAnnotatable: true
});
savedAnnotations = signal<Annotation[]>([]);
}2. Add to your Template
Pass your file, your list of annotations, and your custom templates:
<div class="reviewer-layout">
<lib-file-annotator
#annotator
[file]="currentFile()"
[annotations]="savedAnnotations()"
[creationTemplate]="creationPopup"
[annotationTemplate]="viewPopup"
[markerTemplate]="customMarker"
(annotationCreated)="onAnnotationCreated($event)"
(annotationHovered)="onAnnotationHovered($event)"
></lib-file-annotator>
</div>
<ng-template #customMarker let-label let-highlighted="highlighted">
<div class="custom-marker" [class.is-highlighted]="highlighted">A</div>
</ng-template>
<ng-template #creationPopup let-position>
<div class="custom-popover">
<h3>New Issue</h3>
<button (click)="annotator.commitDraft({ priority: 'High' })">Save</button>
<button (click)="annotator.cancelDraft()">Cancel</button>
</div>
</ng-template>📖 API Reference
Inputs
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| file | FileItem | (Required) | The image or PDF file to render. |
| annotations | Annotation[] | [] | Array of existing annotations to draw on the document. |
| readonly | boolean | false | If true, disables clicking the canvas to create new drafts. |
| creationTemplate | TemplateRef | (Required) | Template rendered inside the CDK overlay when placing a new draft marker. |
| annotationTemplate | TemplateRef | undefined | Template rendered when an existing marker is clicked. |
| markerTemplate | TemplateRef | undefined | Custom template for the marker pin itself. |
| markerAnchorX / Y | number | 50 | Center-point anchor percentage for custom markers. |
| popoverPadding | number | 16 | Padding constraint for the CDK overlay viewport boundaries. |
| draftAnchor / annotationAnchor | string | '16px' | CSS spacing string to offset the popovers from the marker. |
| highlightDuration | number | 2000 | Duration (ms) the highlighted flag stays true after scrolling to a marker. |
| unsupportedActionLabel | string | 'Download File' | Text label for the fallback button displayed on unsupported file types. |
| showPagination | boolean | false | Displays previous/next page navigation controls for PDF files. |
| showPageSelector | boolean | false | Displays a page number selector/input for direct PDF page navigation. |
Outputs
| Event | Payload | Description |
|-------|---------|-------------|
| annotationCreated | Annotation | Fired when annotator.commitDraft(metadata) is called. |
| annotationClicked | Annotation | Fired when a user clicks on an existing marker. |
| annotationHovered | AnnotationHoveredEvent | Fired when a user's mouse enters or leaves a marker. |
| annotationRemoved | Annotation | Fired when annotator.removeAnnotation(annotation) is called. |
| unsupportedActionClicked | FileItem | Fired when the action button on an unsupported file type is clicked. |
Methods (Accessible via @ViewChild or #templateRef)
| Method | Parameters | Description |
|--------|------------|-------------|
| scrollToAnnotation() | annotation: Annotation | Smoothly scrolls the canvas to the specified annotation and triggers the highlight state. |
| commitDraft() | metadata: TMetadata | Finalizes the current draft position and emits the annotationCreated event. |
| cancelDraft() | none | Discards the currently open draft popover. |
| removeAnnotation() | annotation: Annotation | Triggers the annotationRemoved output for the selected annotation. |
Writable Signals (Accessible via #templateRef)
| Signal | Type | Description |
|--------|------|-------------|
| selectedAnnotation | WritableSignal<Annotation \| null> | Holds the currently selected annotation. Set to null to close the annotation popover programmatically. |
| draftPosition | WritableSignal<AnnotationPosition \| null> | Holds the current draft marker position. Cleared automatically after commitDraft() or cancelDraft(). |
