Loupe for developers — add document viewing to your app

Step 1

Install

Run this in your application folder:

Terminal

1npm install https://github.com/AndreiLocota/loupe/releases/download/v0.1.3/andreilocota-loupe-0.1.3.tgz

Download package Licence Package README Source on GitHub

One package (@andreilocota/loupe 0.1.3) includes PDF, Word, images and optional React bindings.
No GitHub account, repository clone or Loupe build is needed.
Your app still needs a bundler, such as Vite. We develop with Node.js 24 LTS.
Downloaded from the Loupe GitHub release, not the public npm registry. SHA-256: c0f59f1918ddd5462f7a3c0a0695bfe71b6ee0831e1f7238b756cbd43db397d4

Shortcut

Let your AI agent do it

Copy this JSON into your coding agent to add Loupe to your app.

Agent prompt (JSON)

{
  "task": "Add Loupe document viewing to this app.",
  "install": "npm install https://github.com/AndreiLocota/loupe/releases/download/v0.1.3/andreilocota-loupe-0.1.3.tgz",
  "docs": "https://tryloupe.lovable.app/developers",
  "package_readme": "https://tryloupe.lovable.app/downloads/README.md",
  "requirements": [
    "Inspect this app and follow its framework, package manager and UI conventions.",
    "Use @andreilocota/loupe with /pdf, /docx and /image adapters; use /react only if this app uses React. Read the linked documentation for the actual API.",
    "Add local file selection and a viewer with a definite height, loading and error states, and page/zoom controls where supported. Process documents in the browser; no hosted API or API key is required.",
    "Load adapters only in browser code in SSR apps. Ensure workers/WASM resolve, clean up the viewer on unmount, and verify a production build and real document rendering."
  ],
  "licence": "Free for personal, commercial and production use. No separate approval is required. You may ship Loupe within your applications; standalone redistribution of the library, SDK or package is prohibited.",
  "licence_text": "https://tryloupe.lovable.app/downloads/LOUPE-LICENSE.txt"
}

Step 2

Open a Word file

In a browser app using Vite, add a file input and a viewer element with a definite height:

index.html

1<input id="file" type="file" accept=".docx,.docm" />
2<div id="viewer" style="height: 75vh"></div>

Create a viewer, register the Word adapter, mount it and load the chosen file:

main.ts

1import { ViewerStore } from '@andreilocota/loupe';
2import { createDocxAdapterFactory } from '@andreilocota/loupe/docx';
3
4const viewer = new ViewerStore();
5viewer.registerFactory(createDocxAdapterFactory());
6viewer.setMountElement(document.querySelector<HTMLElement>('#viewer')!);
7
8document.querySelector<HTMLInputElement>('#file')!.onchange = async (event) => {
9  const file = (event.target as HTMLInputElement).files?.[0];
10  if (!file) return;
11  try {
12    await viewer.loadDocument({ data: file, fileName: file.name }, { initialZoom: 'fit-page' });
13  } catch (error) {
14    console.error('Could not open document', error);
15  }
16};

Clean up when done:

Cleanup

1// When your component unmounts:
2viewer.closeDocument();
3viewer.setMountElement(null);

For PDF use createPdfAdapterFactory from @andreilocota/loupe/pdf; for images use createImageAdapterFactory from @andreilocota/loupe/image. Vite emits the PDF, TIFF and Word workers and the WASM file automatically. In SSR apps, import adapters only in browser code. The playground shows eight sample formats.

Context

What you tried

The Loupe library

Renders, searches, selects text, zooms and navigates documents. That is what you get in your app.

The Word inspector

Adds retained changes, comments, findings and a timeline. These are demo application features, not part of the library API.

The browser demo currently accepts Word files only; the local reference viewer handles every supported format. Back to the demo

API

Entry points

@andreilocota/loupeHeadless core: ViewerStore, types, errors, events
@andreilocota/loupe/docxWord adapter: createDocxAdapterFactory
@andreilocota/loupe/pdfPDF adapter: createPdfAdapterFactory
@andreilocota/loupe/imageImage adapter: createImageAdapterFactory
@andreilocota/loupe/reactOptional React bindings; needs your react + react-dom >= 18

React is optional: /react uses your app's own React and React DOM 18 or newer. APIs are pre-1.0 and can change.

ViewerStorecore class

The headless viewer state container. Format adapters are registered on it with registerFactory().

ViewerProviderreact component

Provides a ViewerStore to the React tree.

ViewerSurfacereact component

Renders the document surface. All surrounding chrome is yours to build.

useViewer(store)react hook

Returns viewer state plus the document and view actions.

state · loadDocument · closeDocument · goToPage · setZoom · search · clearSearch · nextSearchMatch · previousSearchMatch

usePageNavigation(viewer)react hook

Page-level navigation helpers derived from the viewer.

currentPage · pageCount · goToPage · goToNext · goToPrev

useZoom(viewer)react hook

Exposes setZoom, with fit-width and fit-page fit modes.

setZoom · fit-width · fit-page

useCapabilities(store?)react hook

Lets the UI gate format-specific features, so controls only appear where the adapter supports them.

Capabilities

Format support

Feature support by document format in Loupe
Format	Render	Page navigation	Zoom	Text selection	Search + match highlight	Thumbnails	Rotation	Layers	Annotation inspection
PDF .pdf@andreilocota/loupe/pdf	Supported	Supported	Supported	Supported	Supported	Supported	Supported	Supported	Supported
DOCX .docx@andreilocota/loupe/docx	Supported	Supported	Supported	Supported	Supported	opt-in (supported when enabled)	Not provided	Not provided	Not provided
DOCM .docm@andreilocota/loupe/docx	Supported	Supported	Supported	Supported	Supported	opt-in (supported when enabled)	Not provided	Not provided	Not provided
JPEG .jpg, .jpeg@andreilocota/loupe/image	Supported	Not provided	Supported	Not provided	Not provided	Not provided	Not provided	Not provided	Not provided
PNG .png@andreilocota/loupe/image	Supported	Not provided	Supported	Not provided	Not provided	Not provided	Not provided	Not provided	Not provided
GIF .gif@andreilocota/loupe/image	Supported	Not provided	Supported	Not provided	Not provided	Not provided	Not provided	Not provided	Not provided
WebP .webp@andreilocota/loupe/image	Supported	Not provided	Supported	Not provided	Not provided	Not provided	Not provided	Not provided	Not provided
SVG .svg@andreilocota/loupe/image	Supported	Not provided	Supported	Not provided	Not provided	Not provided	Not provided	Not provided	Not provided
TIFF .tif, .tiff@andreilocota/loupe/image	Supported	Supported	Supported	Not provided	Not provided	Supported	Supported	Not provided	Not provided
HEIC .heic@andreilocota/loupe/image	Supported	Not provided	Supported	Not provided	Not provided	Not provided	Not provided	Not provided	Not provided
HEIF .heif@andreilocota/loupe/image	Supported	Not provided	Supported	Not provided	Not provided	Not provided	Not provided	Not provided	Not provided

Key: check = supported, dash = not provided, opt-in = off by default, enable in adapter options.

Word thumbnails are opt-in. DOCM files are viewed as Word documents; macros are never run.
Only TIFF exposes pages, thumbnails and rotation among images; other images are a single view without rotation.
HEIC and HEIF use a decoder that loads only when such a file is opened.
No OCR: images have no text selection or search. PDF search and selection need text in the document. PDF search matches phrases split across font styles and line breaks, highlighting every part together.

Embedding

Runtime assets

Workers and WASM your application serves

DOCX
A WebAssembly module plus a worker. Point the adapter at the WASM URL you serve, for example /assets/docx_parser_bg.wasm.
PDF
A dedicated worker for parsing and rendering off the main thread.
TIFF
A worker used for decoding, including multi-page TIFF documents.
HEIC
A dynamically loaded dependency, pulled in only when a HEIC file is opened.

If your bundler needs explicit URLs

Copy the assets into your public folder (repeat when upgrading), then pass the URLs:

Terminal

1npx loupe-assets public/loupe

Explicit asset URLs

1createPdfAdapterFactory('/loupe/pdf.worker.js');
2createImageAdapterFactory({ tiffWorkerUrl: '/loupe/tiff.worker.js' });
3createDocxAdapterFactory({ wasmUrl: '/loupe/docx_parser_bg.wasm' });

Terms

Licence

Free for personal, commercial and production use. No separate approval is required. You may ship Loupe within your applications; standalone redistribution of the library, SDK or package is prohibited. Loupe is not open source. The Loupe Use Licence is the complete terms for the package and the source.

Source on GitHub, under the same use licence (LICENSE): AndreiLocota/loupe

Add document viewing to your app.