---
name: capture-vision-web
description: Dynamsoft SDKs in the browser with JavaScript and TypeScript. Covers barcode and QR scanning, MRZ and passport reading, document edge detection and normalization, label text recognition, PDF input, React/Vue/Angular/Next asset paths, licensing, and the camera and cleanup pitfalls that break web capture.
---
# Capture Vision on the web
One package, one router, several capabilities. The capability is chosen by the **template string**
you pass to `capture()` / `startCapturing()`, not by a different API:
| Capability | Template |
| --- | --- |
| Barcodes / QR | `ReadBarcodes_Default` (`ReadSingleBarcode`, `ReadBarcodes_SpeedFirst`, `ReadBarcodes_ReadRateFirst`) |
| Document boundaries | `DetectDocumentBoundaries_Default` |
| Boundaries + normalization | `DetectAndNormalizeDocument_Default` |
| Normalize with your own corners | `NormalizeDocument_Default` |
| MRZ (passport / ID) | `ReadPassportAndId` (`ReadPassport`, `ReadId`) |
| Text lines / labels | `RecognizeTextLines_Default` |
## Which package
| Need | Package | Version |
| --- | --- | --- |
| Barcode only | `dynamsoft-barcode-reader-bundle` | 11.6.5000 |
| Barcode + document + MRZ + labels | `dynamsoft-capture-vision-bundle` | 3.6.5000 |
| A preset document scan screen (no custom UX) | `dynamsoft-document-scanner` | 1.5.0 |
| A preset MRZ scan screen (no custom UX) | `dynamsoft-mrz-scanner` | 4.1.0 |
The first two expose the same classes (`LicenseManager`, `CaptureVisionRouter`, `CameraEnhancer`,
`CameraView`, `CapturedResultReceiver`); only the import changes. The last two are higher-level
products with a preset UI. Use them when that screen is exactly what the product needs; **any
custom UX or workflow must use the Capture Vision native interfaces** (`CaptureVisionRouter` +
templates), not these wrappers.
```bash
npm install dynamsoft-capture-vision-bundle@3.6.5000
```
Do not install `dynamsoft-barcode-reader`, which stopped at v10.
## License
1. `get_trial_license` with the product (`dcv` for the full bundle, `dbr` for barcode-only, `mds`
for the Document Scanner, `mrz` for the MRZ Scanner) and `package: "web"`.
2. `status: "login_required"` means a browser window opened — ask the user to finish the Google
sign-in, then call again. The session is reused.
3. Store `licenseKey` in a build-time environment variable (`VITE_DYNAMSOFT_LICENSE_KEY`,
`NEXT_PUBLIC_…`) and show only `licenseKeyMasked` in chat.
4. `get_license_guide` with `platform: "web"` returns the init call for the package you chose.
Never put a literal key in generated source, and never load it from a URL or a checked-in file.
```js
import { LicenseManager } from "dynamsoft-capture-vision-bundle";
await LicenseManager.initLicense(import.meta.env.VITE_DYNAMSOFT_LICENSE_KEY);
```
## Camera scanner (barcode)
Self-host the bundle so wasm and models come from the app's own origin:
```bash
mkdir -p public
cp node_modules/dynamsoft-capture-vision-bundle/dist/dcv.bundle.min.js public/
```
```html
Starting…
```
## Images and PDFs
Same router, no camera:
```js
import { CaptureVisionRouter, EnumCapturedResultItemType } from "dynamsoft-capture-vision-bundle";
const router = await CaptureVisionRouter.createInstance();
const result = await router.capture(blob, "ReadBarcodes_Default");
for (const item of result.items ?? []) {
if (item.type !== EnumCapturedResultItemType.CRIT_BARCODE) continue;
console.log(item.formatString, item.text, item.location);
}
```
Verified against `dynamsoft-barcode-reader-bundle` 11.6.5000 and
`dynamsoft-capture-vision-bundle` 3.6.5000:
- `capture()` accepts a **`Blob`**, a URL string, a base64 string, an `HTMLImageElement`,
`HTMLCanvasElement` or `HTMLVideoElement`. It does **not** accept a `Uint8Array` — passing one
throws `Type of 'imageOrFile' should be ...`.
- There is no `result.barcodeResultItems` on these builds. Iterate `result.items` and filter on
`item.type`, or read `result.decodedBarcodesResult.items` from a receiver callback.
- For a PDF, render the pages (pdf.js) and capture each page as a blob — the web build does not page
through a PDF by itself.
## Document capture
Document and MRZ templates ship **only with the Capture Vision bundle**. Asking the barcode-only
`dynamsoft-barcode-reader-bundle` for `DetectDocumentBoundaries_Default` fails with
`[capture] [-10036] The template name is invalid.` — a common wrong turn when the project installed
the smaller package.
```js
import { CaptureVisionRouter, EnumCapturedResultItemType } from "dynamsoft-capture-vision-bundle";
const result = await router.capture(blob, "DetectAndNormalizeDocument_Default");
for (const item of result.items ?? []) {
switch (item.type) {
case EnumCapturedResultItemType.CRIT_DETECTED_QUAD: // corners of the page
console.log(item.location?.points);
break;
case EnumCapturedResultItemType.CRIT_DESKEWED_IMAGE: // corrected image
console.log(item.image ?? item);
break;
}
}
```
Result item types in this build: `CRIT_ORIGINAL_IMAGE = 1`, `CRIT_BARCODE = 2`, `CRIT_TEXT_LINE = 4`,
`CRIT_DETECTED_QUAD = 8`, `CRIT_DESKEWED_IMAGE = 16`, `CRIT_PARSED_RESULT = 32`,
`CRIT_ENHANCED_IMAGE = 64`. Check `item.type` rather than relying on an aggregate getter.
No item means "no document found in this frame" — a normal result, not an error. For a live flow, run
`DetectDocumentBoundaries_Default` while framing and call `capture()` with
`DetectAndNormalizeDocument_Default` only when the user confirms; normalizing every frame is
expensive.
Resolution matters: a 640×480 frame cannot produce a readable A4 page. Request 1920×1080 or higher
and capture from a still frame.
## MRZ
```js
import { CaptureVisionRouter, EnumCapturedResultItemType } from "dynamsoft-capture-vision-bundle";
const result = await router.capture(blob, "ReadPassportAndId");
const parsed = (result.items ?? []).find(
(item) => item.type === EnumCapturedResultItemType.CRIT_PARSED_RESULT
);
if (parsed) {
console.log(parsed.codeType); // MRTD_TD1_ID | MRTD_TD2_ID | MRTD_TD3_PASSPORT
console.log(parsed.getFieldValue("documentNumber"));
console.log(parsed.getFieldValue("dateOfExpiry"));
}
```
MRZ templates, like document templates, are only in the Capture Vision bundle — the barcode-only
bundle rejects them as an invalid template name.
Field names are camelCase: `documentType`, `firstName`, `lastName`, `sex`, `nationality`,
`documentNumber`, `dateOfBirth`, `dateOfExpiry`, `issuingState`. `ReadPassport` on an ID card
returns nothing — default to `ReadPassportAndId`.
The MRZ Scanner web SDK (`dynamsoft-mrz-scanner`) carries its own scan UI and pipeline — use it
when that screen fits. When the MRZ UX or workflow must be custom, use the templates above
instead; the packaged scanner is not designed to be reshaped.
## Labels and structured content
`RecognizeTextLines_Default` returns text-line items for zonal text (price tags, VIN plates, ID
cards). Pair it with the Code Parser to turn raw strings into typed fields — for example VIN, GS1 AI,
AAMVA. Ask for the specific parser you need rather than writing a regex by hand when a parser exists.
## Bundler apps
A bundler hides the SDK's own script URL, so the engine fetches `*.wasm` from the app origin, gets
`index.html`, and the browser reports `Unexpected token '<'`. Set the root **before** `initLicense`:
```ts
import { CoreModule } from "dynamsoft-capture-vision-bundle";
CoreModule.engineResourcePaths.rootDirectory = "/dynamsoft/";
```
The property is `rootDirectory`, not `root`. Copy assets under the path the SDK appends:
```bash
mkdir -p public/dynamsoft/dynamsoft-capture-vision-bundle@3.6.5000
cp -r node_modules/dynamsoft-capture-vision-bundle/dist \
public/dynamsoft/dynamsoft-capture-vision-bundle@3.6.5000/
```
`references/frameworks.md` has the React hooks pattern (with `StrictMode` handling) and the same
lifecycle translated to Vue and Angular.
## Pitfalls
1. **Camera needs a secure context** — HTTPS or `http://localhost`, otherwise `getUserMedia` is
undefined and nothing starts.
2. **Dispose everything** — `router.dispose()`, `enhancer.dispose()`, `view.dispose()`, and empty the
container. React `StrictMode` mounts twice in development and leaks a camera stream otherwise.
3. **`startCapturing` needs an open enhancer** — open the camera first.
4. **Do not default to the RTU wrappers** (`BarcodeScanner`, `DocumentScanner`, `MRZScanner`). They
have a fixed UI and little control; use `CaptureVisionRouter` for anything real.
5. **One router per scanner instance**; reusing a disposed router throws.
6. **Templates are strings** — enums are convenience wrappers whose `.value` is the string.
## Verify
- `initLicense` resolves before any capture call.
- No 404 for `*.wasm` or `*.worker.js` in the network panel.
- The camera indicator turns off after unmount.
- A still image decodes in the same page, which separates camera problems from decode problems.
## Samples
- JavaScript barcode samples: https://github.com/Dynamsoft/barcode-reader-javascript-samples
- Document Normalizer samples: https://github.com/Dynamsoft/document-normalizer-javascript-samples
- Label Recognizer samples: https://github.com/Dynamsoft/label-recognizer-javascript-samples
- Code Parser samples: https://github.com/Dynamsoft/code-parser-javascript-samples
- Document Scanner: https://github.com/Dynamsoft/document-scanner-javascript
- MRZ Scanner JS: https://github.com/Dynamsoft/mrz-scanner-javascript
- Barcode + MRZ + document in one page:
https://github.com/yushulx/javascript-barcode-qr-code-scanner/tree/main/examples/barcode_mrz_document