User Guide for the MRZ Scanner JavaScript Edition
This user guide will walk you through a Hello World sample web application that scans MRZ documents using the MRZ Scanner JavaScript Edition SDK. We recommend using this sample as a reference when creating your own application.
Important: Please visit the Introduction page to learn about the MRZ document formats, the architecture of the MRZ Scanner with respect to other Dynamsoft products, and the system requirements of the MRZ Scanner JavaScript Edition.
License
Trial License
When getting started with MRZ Scanner, we recommend getting your own 30-day trial license through the customer portal. The trial license can be renewed via the same customer portal twice, each time for another 15 days, giving you a total of 60 days to develop your own application using the solution. Please contact the Dynamsoft Support Team if you need more time for a full evaluation.
Note: The MRZ Scanner license contains a license for the Dynamsoft Label Recognizer, Dynamsoft Code Parser, and the Dynamsoft Camera Enhancer since the MRZ Scanner builds on top of those three products.
Full License
If you are fully satisfied with the solution and would like to move forward with a full license, please contact the Dynamsoft Sales Team.
Quick Start - Hello World
As mentioned previously, the purpose of this guide is to help you implement a Hello World application using the MRZ Scanner solution. To showcase this, we will be using vanilla JS. You can find the full code in the samples Github repo.
The first step before writing the code is to include the SDK in your application. You can simply include the SDK by using the precompiled script, but you can also build the SDK from source yourself.
The simplest way to include the SDK is to use either the jsDelivr or UNPKG CDN. The Hello World sample that this guide will explore uses jsDelivr:
-
jsDelivr
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-mrz-scanner@2.0.0/dist/mrz-scanner.bundle.js"></script>
-
UNPKG
<script src="https://unpkg.com/dynamsoft-mrz-scanner@2.0.0/dist/mrz-scanner.bundle.js"></script>
When using a framework such as React, Vue or Angular, we recommend adding the package as a dependency using a package manager such as npm or yarn:
npm i dynamsoft-mrz-scanner@2.0.0 -E
# or
yarn add dynamsoft-mrz-scanner@2.0.0 -E
Important Note:
When using a package manager like npm or yarn, you likely need to specify the location of the engine files as a link to a CDN. Please see the MRZScannerConfig API for a code snippet on how to set the engineResourcePaths.
Below is the complete Hello World sample page that uses the precompiled script served via a CDN.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Dynamsoft MRZ Scanner - Hello World</title>
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-mrz-scanner@2.0.0/dist/mrz-scanner.bundle.js"></script>
</head>
<body>
<h1 style="font-size: large">Dynamsoft MRZ Scanner</h1>
<script>
// Initialize the Dynamsoft MRZ Scanner
const mrzScanner = new Dynamsoft.MRZScanner({
license: "YOUR_LICENSE_KEY_HERE",
});
(async () => {
// Launch the scanner and wait for the result
const result = await mrzScanner.launch({});
})();
</script>
</body>
</html>
Note:
This code is identical to the Hello World file mentioned in Build from Source, except for the script source.
Please do not forget to replace ‘YOUR_LICENSE_KEY_HERE’ with your own license key, whether it is trial or full.
To run the sample, create a new file called hello-world.html
, then copy and paste the code above into the file. Next, serve the page directly by deploying it to a server.
If you are using VS Code, a quick and easy way to serve the project is using the Five Server VSCode extension. Simply install the extension, open the hello-world.html
file in the editor, and click “Go Live” in the bottom right corner of the editor. This will serve the application at http://127.0.0.1:5500/hello-world.html
.
Alternatively, you can use other methods like IIS
or Apache
to serve the project, though we will omit those methods here for brevity.
Breaking down Hello World
Let’s now go through the code of the Hello World sample to understand how the code works in detail.
Step 1: Setting up the HTML and Including the MRZ Scanner
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Dynamsoft MRZ Scanner - Hello World</title>
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-mrz-scanner@2.0.0/dist/mrz-scanner.bundle.js"></script>
</head>
<body>
<h1 style="font-size: large">Dynamsoft MRZ Scanner</h1>
</body>
</html>
The first step in setting up the HTML in the Hello World project is to include the SDK. (We discussed the two available methods to include the SDK resources in the earlier section Quick Start section) In this example, we include the precompiled MRZ Scanner SDK script via CDN in the header:
MRZ Scanner comes with a Ready-to-Use UI. When the MRZ Scanner launches, it creates a container which it populates with the Ready-to-Use UI.
Step 2: Initializing the MRZ Scanner
// Initialize the Dynamsoft MRZ Scanner
const mrzscanner = new Dynamsoft.MRZScanner({
license: "YOUR_LICENSE_KEY_HERE",
});
Above is the simplest way to initialize the MRZ Scanner. Note the configuration object used to set the behaviour of the MRZ Scanner instance. The single property that is required to be defined in this configuration object is the license key. Without a valid license, the MRZ Scanner view fails to launch, and the user will be met with a license key error message. Please refer to the licensing section of the guide for instructions on acquiring a license key.
Step 3: Launching the MRZ Scanner
(async () => {
// Launch the scanner and wait for the result
const result = await mrzscanner.launch({});
console.log(result);
})();
Now that the MRZ Scanner has been initialized and configured, it is ready to be launched! Upon launch, the MRZ Scanner presents the main MRZScannerView UI in its container on the page, and is ready to start scanning. Upon scanning an MRZ (via video or static image), the MRZ Scanner then switches to the MRZResultView , which displays a cropped image of the MRZ document as well as the parsed fields of the MRZ text. Let’s break down these two Views:
MRZScannerView
The MRZScannerView
is composed of the following UI elements:
-
Camera View: The Camera View is the camera viewfinder UI component within the
MRZScannerView
. This viewfinder occupies the majority of the space within the MRZScannerView to give the user a clear view and precise control of the image being scanned. -
Scan Guide Frame: The Scan Guide Frame is an overlay placed on top of the Camera View that guides the user to place the MRZ document in the middle of the Camera View, in order to achieve a fast and accurate scan. The guide frame is enabled by default, but may be hidden via the MRZScannerViewConfig interface. Note that if scan guide frame is enabled, the scanner also crops out the region outside the guide frame.

- Format Selector: Below the scan guide frame, you will also notice a selector box that allows the user to choose which formats the MRZ Scanner should recognize. The formats that show up in the format selector are configurable via the MRZScannerConfig interface, while the visibility of the format selector itself is configurable via the MRZScannerViewConfig interface. To learn about MRZ formats, please refer to the Introduction page.

-
Resolution/Camera Select Dropdown: This dropdown allows the user to switch cameras (should they have more than one available on the device), or select a different resolution for the camera that is currently selected.
-
Load Image Button: This button allows the user to scan a file of an MRZ-containing image from the device’s local storage.
-
Sound Button: When toggled on, the MRZ Scanner plays a beep sound to signal when the scanner recognizes an MRZ.
-
Flash Button: This button is responsible for toggling the flash of the camera (when one is available). The flash button does not appear if the device does not have a camera flash, or the browser does not support camera flash.
-
Close Scanner Button: This button closes the MRZ Scanner and takes the user back to the landing page.
MRZResultView
Here is a quick breakdown of the constituent UI elements of the result view:
-
Original Image: A cropped image of the scanned MRZ document - this gets displayed at the top of the
MRZResultView
by default. -
Parsed Results: The data parsed from the MRZ code, displayed with their corresponding field names (e.g. Given Name, Nationality, etc.) are placed below the cropped image of the MRZ corresponding field names. In addition to displaying these parsed results, the MRZ Scanner allows the user to edit the values of the fields in case of any errors by cross referencing from the cropped MRZ document displayed directly above.
-
Re-take Button: This button discards the previous scan and parsed data, then takes the user back to the MRZScannerView to scan another MRZ document.
-
Done Button: This button closes the scanner and destroys the MRZScanner instance, and returns the result object containing the MRZ scan. At that point, the application goes back to the landing page. You can additionally dictate further actions upon the button click, such as allowing the user to perform some extra actions with the MRZ result, navigating to another page, passing the result object for further processing, and more.
Note: In the Hello World sample, no action is taken once the Done button is clicked. The scanner closes and the user is met with an empty page. In order to open the scanner again, the user must refresh the page. You may choose to implement a more user-friendly behavior in a production environment, such as presenting the user with an option to re-open the MRZ Scanner upon closing it.
Next Steps
Now that you got the most basic functionality of the MRZ Scanner up and running, it’s time to explore the many ways in which you can customize the MRZ Scanner! To learn more about this, please visit Customizing the MRZ Scanner.