PaddleOCR.js: PaddleOCR in JavaScript

Install and first OCR#

npm install @paddleocr/paddleocr-js

// jsDelivr's +esm build rewrites the SDK's bare imports, so this runs as-is
import { PaddleOCR } from "https://cdn.jsdelivr.net/npm/@paddleocr/paddleocr-js@0.4.2/+esm";

The official quick start:¹

import { PaddleOCR } from "@paddleocr/paddleocr-js";

const ocr = await PaddleOCR.create({
  lang: "ch",
  ocrVersion: "PP-OCRv5",
  ortOptions: {
    backend: "auto"
  }
});

const [result] = await ocr.predict(fileOrBlob);
console.log(result.items);

predict always resolves to an array, even for a single File, so destructure it. Inputs can be a Blob/File, ImageBitmap, ImageData, HTMLCanvasElement, HTMLImageElement or an OpenCV cv.Mat, or an array of them.¹

The package is ESM-only. Its dist/index.mjs keeps bare imports (js-yaml, clipper-lib, @techstark/opencv-js, onnxruntime-web), so a browser can't load that file directly. You need a bundler, an import map, or jsDelivr's +esm URL above. We use the +esm import in production on our online tool, and it works in Chromium with the default main-thread mode.²⁴⁶

Model presets and languages#

Pick models with lang + ocrVersion, or name them explicitly. Three pairs are built in. They download from Baidu's CDN as uncompressed .tar archives:³⁵

// PP-OCRv6 tiny has no lang mapping: name the models
await PaddleOCR.create({
  textDetectionModelName: "PP-OCRv6_tiny_det",
  textRecognitionModelName: "PP-OCRv6_tiny_rec"
});

The Latin set for PP-OCRv6 includes fr, de, es, pt, it, nl, pl, tr, vi, id, cs, sv and more. Every code in the SDK's Latin list works except pi. Korean, Cyrillic, Arabic, Thai and Devanagari models are not available in the SDK. Use the Python library for those (see the language list).³

PP-OCRv6 medium, the Python default, isn't built in. Small is the most accurate model the SDK ships. In our CPU benchmark it matched medium on three of five documents.

Construction options#

Other methods are ocr.initialize(), ocr.getInitializationSummary() and ocr.dispose(). Call dispose() when you're done, because the ONNX sessions hold a lot of memory.¹

predict() parameters and result shape#

The second argument takes the same tuning knobs as Python, in camelCase or snake_case:¹

const [result] = await ocr.predict(imageBitmap, {
  textDetLimitSideLen: 64,     // or text_det_limit_side_len
  textDetLimitType: "min",
  textDetMaxSideLimit: 4000,
  textDetThresh: 0.3,
  textDetBoxThresh: 0.6,       // lower (e.g. 0.4) to catch faint text
  textDetUnclipRatio: 1.5,     // raise (e.g. 2.0) if letters get clipped
  textRecScoreThresh: 0.0      // drop lines below this confidence
});

The values shown are the SDK's default detection config.³ Each result looks like this:

{
  image:   { width, height },
  items:   [{ text: "Order #4471", score: 0.97, poly: [[x, y], [x, y], [x, y], [x, y]] }, ...],
  metrics: { detMs, recMs, totalMs, detectedBoxes, recognizedCount },
  runtime: { /* requested backend and provider metadata */ }
}

When you pass several images, detectedBoxes and recognizedCount are per image. detMs/recMs/totalMs cover the whole call and are identical on every element.¹ For Python users: items[i].text is rec_texts[i], score is rec_scores[i] and poly is rec_polys[i].

WebGPU vs WASM, threads and COOP/COEP#

With backend: "auto", the SDK asks navigator.gpu for an adapter. It uses WebGPU if it gets one and WebAssembly otherwise. "webgpu" throws if WebGPU is unavailable, and "wasm" always uses the CPU.³ Your app is responsible for:¹

• COOP/COEP headers "when enabling threaded WASM or WebGPU". The official Vite demo sends Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: credentialless. Without cross-origin isolation, the browser has no SharedArrayBuffer, so WASM runs single-threaded.
• Where the .wasm files come from (ortOptions.wasmPaths). In main-thread mode your bundler normally copies them from node_modules/onnxruntime-web/dist/.
• A bundler that can emit module workers, if you use worker: true.

export default defineConfig({
  worker: { format: "es" },
  server: {
    headers: {
      "Cross-Origin-Opener-Policy": "same-origin",
      "Cross-Origin-Embedder-Policy": "credentialless"
    }
  }
});

Our online tool sends no COOP/COEP headers and still works. It's just single-threaded WASM when WebGPU isn't available. The measurements below were taken that way.⁶

Worker mode#

Inference blocks the thread it runs on. To keep your UI responsive, use the SDK's own worker. Here is the official example:¹

import { PaddleOCR } from "@paddleocr/paddleocr-js";

const ocr = await PaddleOCR.create({
  lang: "ch",
  ocrVersion: "PP-OCRv5",
  worker: true,
  ortOptions: {
    backend: "wasm",
    wasmPaths: "https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/",
    numThreads: 2,
    simd: true
  }
});

• It uses the package's worker, not ONNX Runtime's env.wasm.proxy, which it switches off to avoid nested workers. cv.Mat inputs aren't supported, and the browser needs OffscreenCanvas.¹³
• Pin wasmPaths to the ONNX Runtime version you actually ship. If it's unset, the 0.4.2 build falls back to onnxruntime-web@1.24.3 on jsDelivr and logs a warning. The unversioned URL in the example above floats to whatever is latest.³
• The worker bundle is large: dist/assets/worker-entry-*.js is 11.3 MB in 0.4.2.⁴ We have not tested worker mode through the +esm CDN build. Use a bundler for it.

Drawing results: the viz subpath#

@paddleocr/paddleocr-js/viz renders the PaddleOCR-style side-by-side image: boxes on the original at left, recognized text at right. For Chinese or Japanese text, load a CJK font.¹

import { renderOcrToBlob } from "@paddleocr/paddleocr-js/viz";

const blob = await renderOcrToBlob(imageBitmap, result, {
  font: { family: "Noto Sans SC", source: "/fonts/NotoSansSC-Regular.ttf" }
});

It takes a single OcrResult, not the array. There is also an OcrVisualizer class with toBlob() and dispose(), and deterministicColor(index) for matching colors in your own overlays.¹

Production model loading: what we learned building /online#

By default the SDK fetches models from paddle-model-ecology.bj.bcebos.com each time you call create().³ Three things went wrong for us in production, and the loader on our site handles each of them:⁶

1. CORS headers come and go. Baidu's CDN reflects your Origin in Access-Control-Allow-Origin most of the time. In one batch of 16 requests, one response had no CORS header. That happened even with a site-specific query string to avoid a shared cache entry. In a browser that is a hard failure.
2. Downloads are big: 31.2 MB for small, 21.5 MB for v5 mobile, 6.3 MB for tiny. You don't want users downloading them again on every visit.
3. The SDK gives no progress events for model downloads.

The fix is to fetch the archives yourself, then hand the SDK blob: URLs through textDetectionModelAsset / textRecognitionModelAsset. Retry Baidu once with a fresh query string. If that fails, fall back to the identical ONNX export on Hugging Face (PaddlePaddle/<model>_onnx). Hugging Face hosts inference.onnx and inference.yml as loose files, so pack them into the uncompressed tar the SDK expects. Store the result in Cache Storage. Condensed from our ocr-engine.mjs:

const BOS = "https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/";
const HF  = "https://huggingface.co/PaddlePaddle/";

async function getBytes(url) {
  const r = await fetch(url, { mode: "cors" });
  if (!r.ok) throw new Error(`HTTP ${r.status} ${url}`);
  return new Uint8Array(await r.arrayBuffer());
}

async function getModel(name) {                 // e.g. "PP-OCRv6_small_det"
  const cache = await caches.open("ocr-models-v1");
  const key = `/models/${name}.tar`;
  const hit = await cache.match(key);
  if (hit) return URL.createObjectURL(await hit.blob());

  let blob;
  for (const q of ["?src=myapp", `?r=${Math.random().toString(36).slice(2)}`]) {
    try { blob = new Blob([await getBytes(`${BOS}${name}_onnx_infer.tar${q}`)]); break; }
    catch { /* missing CORS header or network error: try again */ }
  }
  if (!blob) {                                  // same ONNX files, different host
    const base = `${HF}${name}_onnx/resolve/main/`;
    const [onnx, yml] = await Promise.all([getBytes(base + "inference.onnx"), getBytes(base + "inference.yml")]);
    blob = buildTar([{ name: "inference.onnx", bytes: onnx }, { name: "inference.yml", bytes: yml }]);
  }
  await cache.put(key, new Response(blob));
  return URL.createObjectURL(blob);
}

const [det, rec] = await Promise.all([getModel("PP-OCRv6_small_det"), getModel("PP-OCRv6_small_rec")]);
const ocr = await PaddleOCR.create({
  textDetectionModelName: "PP-OCRv6_small_det", textDetectionModelAsset: { url: det },
  textRecognitionModelName: "PP-OCRv6_small_rec", textRecognitionModelAsset: { url: rec },
  ortOptions: { backend: "auto" }
});
// buildTar(): a ~30-line ustar writer (512-byte headers, zero padding, two empty
// trailing blocks). See tarHeader()/buildTar() in /assets/ocr-engine.mjs.

The model names must stay the same as in inference.yml. The SDK checks that model_name matches the name you pass. Wrap caches calls in try/catch: Cache Storage can be missing or full in private windows. The full version adds streaming progress and abort support.¹⁶

How fast is it?#

On our photographed receipt, both models found all 27 lines and made the same single slip: 0rder (with a zero) for "Order".⁶ Small is the safer default for mixed documents and Japanese. Tiny makes sense on phones and slow connections when your text is Latin-script or Chinese. Expect faster numbers on a laptop with WebGPU or with threaded WASM behind COOP/COEP.

Custom and fine-tuned models#

A fine-tuned model works if you export it to ONNX and package it the way the SDK expects:¹

• An uncompressed ustar .tar. A .tar.gz fails to parse, because the SDK doesn't gunzip.
• Containing inference.onnx and inference.yml, at the root or in a subfolder (matched by basename).
• model_name in inference.yml must equal the name you pass to create().

# from the folder containing your exported model
tar --format=ustar -cf my_rec_model.tar inference.onnx inference.yml

Mistakes throw an Error during initialization, such as a missing entry, a mismatched model_name or an ONNX load failure. There is no silent fallback.¹ For converting Paddle models to ONNX, see the official "Obtaining ONNX models" doc linked from the browser deployment page.

Node.js, React and other environments#

• Node.js: not documented. The package describes itself as a "Browser-based OCR SDK", depends on onnxruntime-web, and has no Node entry point. On the server, use self-hosted PaddleOCR serving (our Node fetch client is tested), or the hosted API's @paddleocr/api-sdk (Node.js 18+).²
• React / Vue / Next.js: create the instance once, for example in a module-level promise, and only on the client. In Next.js, import it inside useEffect or a client-only dynamic import so it never runs during server rendering.
• Mobile apps: native Android and iOS demos exist in the PaddleOCR repo (deploy/ppocr-android, deploy/ios_demo) if a WebView isn't enough.

Questions#