react-ocr-capture
v0.2.0
Published
A React component that captures a camera frame and runs on-device OCR with PaddleOCR
Maintainers
Readme
react-ocr-capture
A React component that opens the device camera, lets the user capture a frame, and runs on-device OCR over it using PaddleOCR (browser/WASM, no server round-trip).
Install
npm install react-ocr-capturereact (>=18) is a peer dependency and is not bundled.
Usage
import { Ocr } from "react-ocr-capture";
function App() {
return (
<div style={{ height: 480 }}>
<Ocr
lang="en"
ocrVersion="PP-OCRv5"
ortOptions={{ backend: "wasm", wasmPaths: "/ort/" }}
onReady={() => console.log("OCR ready")}
onScore={(score) => console.log("Accuracy:", score)}
onProcessingChange={(processing) => console.log("Processing:", processing)}
onError={(error) => console.error("OCR error:", error)}
onChange={(texts) => console.log("Recognized:", texts)}
/>
</div>
);
}Preload and reuse the OCR engine
Model download and ONNX session creation are expensive. Preload once, then use
the same engineCacheKey on the component so modal unmounts do not recreate the
engine:
import { Ocr, preloadOcr, disposeOcrEngine } from "react-ocr-capture";
const engineOptions = {
lang: "en",
ocrVersion: "PP-OCRv5",
ortOptions: { backend: "wasm", wasmPaths: "/ort/" },
};
await preloadOcr(engineOptions, "module-scanner");
<Ocr
lang="en"
ocrVersion="PP-OCRv5"
ortOptions={engineOptions.ortOptions}
engineCacheKey="module-scanner"
/>
// Release the cached model when the application no longer needs it.
await disposeOcrEngine("module-scanner");Use one cache key per unique engine configuration. Reusing a key with different options returns the engine already stored under that key.
Select smaller or custom models
ocrOptions forwards additional PaddleOCR.create options. For example:
<Ocr
engineCacheKey="module-scanner-tiny"
ortOptions={{ backend: "wasm", wasmPaths: "/ort/" }}
ocrOptions={{
textDetectionModelName: "PP-OCRv6_tiny_det",
textRecognitionModelName: "PP-OCRv6_tiny_rec",
}}
/>Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| lang | string | "en" | OCR language model to load |
| ocrVersion | string | "PP-OCRv5" | PaddleOCR model version |
| ortOptions | OrtOptions | { backend: "auto" } | ONNX Runtime backend and WASM configuration |
| ocrOptions | PaddleOCRCreateOptions excluding the options above | – | Additional PaddleOCR options, including explicit model names/assets and worker mode |
| engineCacheKey | string | – | Reuse a preloaded or previously created OCR engine across component mounts |
| onReady | () => void | – | Called after OCR model initialization |
| onError | (error: unknown) => void | – | Called when camera setup, OCR initialization, or recognition fails |
| onScore | (score: number) => void | – | Called with average recognition confidence from 0 to 100 |
| onProcessingChange | (processing: boolean) => void | – | Called when recognition starts or finishes |
| onChange | (texts: string[]) => boolean \| void \| Promise<boolean \| void> | – | Called with recognized lines. Return false to discard capture and resume camera |
| children | ReactNode | – | Rendered below camera view |
The component requires camera permission (getUserMedia) and must be served over HTTPS (or localhost) to work in most browsers.
Notes
- Styling uses Tailwind utility classes. Tailwind consumers must include the package
distfiles in their content scan; other setups must provide equivalent utility styles. react-iconsis used for the capture/delete button icons.
Build
npm install
npm run buildOutputs ESM, CJS, and type declarations to dist/.
