LightPDF Editor SDK

@lightpdf-sdk/editor is the LightPDF Web PDF editor SDK for browser applications. It exposes the editor as a Web Component named <light-pdf-editor>, so it can be used in Vue, React, Angular, Svelte, or plain HTML applications.

The SDK supports opening PDFs, annotations, editing, saving, localization, theme customization, event handling, and self-hosted runtime resources. The editor UI runs inside Shadow DOM to reduce style conflicts with the host page.

Installation

npm install @lightpdf-sdk/editor

Quick Start

Register the Web Component in your application entry:

import "@lightpdf-sdk/editor/element";

Add the editor to your page:

<light-pdf-editor
  id="editor"
  api-key="your-api-key"
  mode="annot"
  active-tool="annot-select"
></light-pdf-editor>

<input id="file" type="file" accept="application/pdf" />

Give the element an explicit size:

light-pdf-editor {
  display: block;
  width: 100%;
  height: 100vh;
}

Open a PDF:

const editor = document.querySelector("light-pdf-editor");
await editor.ready;

document.querySelector("#file")?.addEventListener("change", async (event) => {
  const input = event.target as HTMLInputElement;
  const file = input.files?.[0];
  if (file) {
    await editor.openPdf(file);
  }
});

Save the edited PDF:

const editedFile = await editor.savePdf();
if (editedFile) {
  const url = URL.createObjectURL(editedFile);
  const link = document.createElement("a");
  link.href = url;
  link.download = editedFile.name || "edited.pdf";
  link.click();
  URL.revokeObjectURL(url);
}

Create an Editor with JavaScript

You can also create the element with JavaScript instead of writing the HTML tag directly:

import {
  createLightPdfEditor,
  type LightPdfEditorElement,
} from "@lightpdf-sdk/editor";

const editor: LightPdfEditorElement = createLightPdfEditor({
  target: "#pdf-editor-container",
  apiKey: "your-api-key",
  locale: "zh",
  mode: "annot",
  activeTool: "annot-select",
});

await editor.ready;

Authorization

When authorization is enabled, pass apiKey before calling protected operations such as openPdf() or savePdf().

HTML attribute:

<light-pdf-editor api-key="your-api-key"></light-pdf-editor>

JavaScript property:

editor.apiKey = "your-api-key";

JavaScript options:

const editor = createLightPdfEditor({
  target: "#container",
  apiKey: "your-api-key",
});

Listen for authorization errors:

editor.addEventListener("license-error", (event) => {
  console.error(event.detail.status, event.detail.message);
});

Runtime Resources

To keep the npm package small, the SDK does not bundle all WASM, font, style, and worker resources into the package. By default, these resources are hosted by LightPDF and loaded automatically.

If you need to self-host runtime resources, override the resource directories with these attributes:

<light-pdf-editor
  api-key="your-api-key"
  asset-base-url="https://static.example.com/lightpdf/edit-pdf/"
  wasm-base-url="https://static.example.com/wasm/lightpdf/pdf-edit/"
  font-base-url="https://static.example.com/font/lightpdf/pdf-edit/"
></light-pdf-editor>

Required resource layout:

asset-base-url/
├── style.css
└── bundledFontDownloadWorker.js

wasm-base-url/
├── pdf-sdk.js
└── pdf-sdk.wasm

font-base-url/
└── ...font files

asset-base-url, wasm-base-url, and font-base-url should point to directories, not individual files.

For cross-origin resources, make sure the server allows CORS and returns the correct MIME types:

| File | Recommended MIME | | --- | --- | | .js | text/javascript or application/javascript | | .css | text/css | | .wasm | application/wasm | | Fonts | font/ttf, font/otf, font/woff, or font/woff2 |

Attributes

| Attribute | JS option/property | Type | Default | Description | | --- | --- | --- | --- | --- | | api-key | apiKey | string | empty | SDK authorization key. | | locale | locale | string | en or environment fallback | Editor language, such as en, zh, tw, or jp. | | mode | mode | annot \| edit | annot | Initial mode. | | active-tool | activeTool | string | mode default | Initial tool. | | asset-base-url | assetBaseUrl | URL | LightPDF hosted resources | Directory for style.css and the bundled font worker. | | wasm-base-url | wasmBaseUrl | URL | LightPDF hosted resources | Directory for pdf-sdk.js and pdf-sdk.wasm. | | font-base-url | fontBaseUrl | URL | LightPDF hosted resources | Font resource directory. | | local-fonts | localFonts | boolean/string | true | Enables browser local font discovery when supported. | | hidden-open-file | hiddenOpenFile | boolean/string | false | Hides the built-in open-file entry. | | no-auto-download | noAutoDownload | boolean/string | false | Disables built-in auto-download for the save button. | | theme | theme | string | default | Theme name. | | no attribute | themeConfig | Record<string, string> | {} | Custom theme tokens, only available through JavaScript. |

Methods

| Method | Returns | Description | | --- | --- | --- | | ready | Promise<void> | Resolves when the Web Component is mounted. | | openPdf(file, options?) | Promise<void> | Opens a File or Blob. options.password can be used for password-protected PDFs. | | savePdf() | Promise<File \| null> | Saves the current document. | | undo() | Promise<boolean> | Runs undo. | | redo() | Promise<boolean> | Runs redo. | | getUndoRedoState() | { canUndo, canRedo } | Returns undo/redo state. | | jumpToPage(pageNumber) | Promise<void> | Jumps to a 1-based page number. | | zoomIn() | Promise<void> | Zooms in. | | zoomOut() | Promise<void> | Zooms out. | | setMode(mode) | void | Switches between annot and edit modes. | | setTool(tool) | void | Switches the active tool. | | setLocale(locale) | void | Updates the editor language. | | getDebugStoreSnapshot() | unknown | Returns an internal state snapshot for debugging only. | | destroy() | void | Removes the element and disposes the editor instance. |

Events

All events are CustomEvents. They bubble and are composed across the Shadow DOM boundary.

| Event | Detail | Description | | --- | --- | --- | | ready | { element, contextId } | The component is mounted. | | options-change | { attribute, options } | An attribute or option changed. | | theme-change | { theme, themeConfig } | Theme changed. | | license-status-change | { status, expiresAt, lastVerifiedAt, message } | Authorization state changed. | | license-error | { status, expiresAt, lastVerifiedAt, message } | Authorization failed. | | load-complete | {} | The editor SDK is initialized. | | open-pdf-callback | { success, sourceFile, message } | PDF open result. | | download-pdf | { success, file, message, sourceFile } | Save or download result. | | download-click | { target } | The user clicked a save or download entry. | | home-click | {} | The user clicked the home button. | | tool-click | { name } | The user clicked a tool. | | ocr-banner-click | { source } | The user clicked the OCR banner. | | more-font-click | {} | The user clicked more fonts. | | font-load-failed | { reason } | Font loading failed. | | ime-viewport-adjust | viewport adjustment data | Mobile IME viewport synchronization. | | ime-anchor-change | input anchor data | Mobile input anchor synchronization. | | error | { message, error } | Generic error. |

Theme

Use theme and themeConfig for lightweight theme customization:

const editor = createLightPdfEditor({
  target: "#container",
  apiKey: "your-api-key",
  theme: "brand",
  themeConfig: {
    "--lp-theme-bg-start": "#eef5ff",
    "--lp-theme-bg-end": "#dceaff",
    "--lp-theme-text": "#102033",
    "--lp-theme-primary": "#2563eb",
  },
});

editor.theme = "brand-alt";
editor.themeConfig = {
  "--lp-theme-bg-start": "#fff7ed",
  "--lp-theme-primary": "#ea580c",
};

Theme configuration only affects the current editor instance and does not pollute the host page or other editor instances.

Troubleshooting

The editor is blank or only partially visible

Make sure the host page gives <light-pdf-editor> an explicit width and height.

Styles fail to load and the MIME type is text/html

This usually means style.css returned a 404 HTML page. Check whether asset-base-url points to the correct directory.

pdf-sdk.js or pdf-sdk.wasm returns 404

Check whether wasm-base-url points to a directory containing both pdf-sdk.js and pdf-sdk.wasm.

Missing API key

Pass api-key or set editor.apiKey before calling openPdf() or savePdf().

Browser Requirements

• A modern browser with ES Modules, Custom Elements, Shadow DOM, and WASM support.
• Use an HTTP server for testing. Do not open test pages through file://.
• Configure CORS correctly when loading WASM, workers, or fonts across origins.