MRZ Scanner JavaScript Edition API Reference

new MRZScanner(config: MRZScannerConfig)

const mrzScanner = new Dynamsoft.MRZScanner({
    license: "YOUR_LICENSE_KEY_HERE",
    returnOriginalImage: true,
    returnDocumentImage: true,
    returnPortraitImage: true,
    scannerViewConfig: {
        // For custom scanning configuration, MRZScannerViewConfig goes in here
    }
});

launch(): Promise<MRZResult>

launch(imageSource: Blob | string | DSImageData | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement): Promise<MRZResult>

(async () => {
    // Launch the scanner and wait for the result
    try {
        const result = await mrzScanner.launch();
        console.log(result); // print the MRZResult to the console
    } catch (error){
        console.error(error);
    }
})();

(async () => {
    // Launch the scanner with a static file
    try {
        const result = await mrzScanner.launch(fileToProcess);
        console.log(result); // print the MRZResult to the console
    } catch (error){
        console.error("Error processing file:", error);
    }
})();

dispose(): void

mrzScanner.dispose();
console.log("Scanner resources released.");

interface MRZScannerConfig {
  license?: string; // license is absolutely required to be set at initialization
  container?: HTMLElement | string;

  // Resource/Template specific configuration
  templateFilePath?: string;
  engineResourcePaths?: EngineResourcePaths;

  // Scanner View Configuration
  scannerViewConfig?: MRZScannerViewConfig;

  mrzFormatType?: Array<EnumMRZDocumentType>;

  // Returned-image flags (control what's attached to the MRZResult)
  returnOriginalImage?: boolean;
  returnDocumentImage?: boolean;
  returnPortraitImage?: boolean;
}

const mrzConfig = {
    license: "YOUR_LICENSE_KEY_HERE",
    // Restrict the scanner to passports and TD1 ID cards.
    // Strings are used here instead of the EnumMRZDocumentType enum for readability.
    mrzFormatType: ["td3_passport", "td1_id"],

    // Return every image the SDK can produce so the result view has full data.
    returnOriginalImage: true,
    returnDocumentImage: true,
    returnPortraitImage: true,

    // engineResourcePaths is required when installing via npm. The paths below
    // assume the DCV folders have been copied into public/ and are served at root.
    // (see the User Guide for the staging setup).
    engineResourcePaths: {
        dcvBundle: "/dynamsoft-capture-vision-bundle/dist/",
        dcvData: "/dynamsoft-capture-vision-data/",
    },
    scannerViewConfig: {
        // the MRZScannerViewConfig goes in here - see MRZScannerViewConfig section
    }
};

// Initialize the Dynamsoft MRZ Scanner with the above MRZScannerConfig object
const mrzScanner = new Dynamsoft.MRZScanner(mrzConfig);

interface MRZScannerViewConfig {
  uiPath?: string;
  container?: HTMLElement | string;

  // Scanner UI visibility toggles
  enableScanRegion?: boolean;
  showLoadImageButton?: boolean;
  showFormatSelector?: boolean;
  showSoundToggle?: boolean;

  enableMultiFrameCrossFilter?: boolean;

  // Load-image flow
  loadImageAcceptedTypes?: string;
  loadImageFileConverter?: (file: File) => Promise<Blob>;

  // Multi-side scanning
  flipDocumentTimeout?: number;

  // UI customization
  toolbarButtonsConfig?: ToolbarButtonsConfig;
  formatSelectorConfig?: FormatSelectorConfig;
  messagesConfig?: MessagesConfig;
  themeConfig?: ThemeConfig;
}

const mrzScanViewConfig = {
    enableScanRegion: true, // capture only the area inside the guide frame; true by default
    showLoadImageButton: true, // show the gallery button in the toolbar; true by default
    showFormatSelector: true, // show the passport/ID/visa/all selector; false by default
    showSoundToggle: false, // hide the sound toggle button; true by default
    enableMultiFrameCrossFilter: true, // multi-frame cross verification; true by default

    flipDocumentTimeout: 3000, // ms to wait for the user to flip the document during multi-side scanning

    loadImageAcceptedTypes: "image/*,application/pdf", // allow PDFs in addition to images
    loadImageFileConverter: async (file) => {
        if (file.type === "application/pdf") {
            // Example PDF to image conversion
            const pdfData = await convertPDFToImage(file);
            return pdfData;
        }
        // For other non-image types, you can add more conversion logic
        // If it's not a supported type, throw an error
        throw new Error("Unsupported file type");
    },
};

const mrzConfig = {
    license: "YOUR_LICENSE_KEY_HERE",
    scannerViewConfig: mrzScanViewConfig
};

interface ToolbarButtonsConfig {
  close?: ToolbarButtonConfig;
  loadImage?: ToolbarButtonConfig;
  cameraSwitch?: ToolbarButtonConfig;
  flash?: ToolbarButtonConfig;
  flashOff?: ToolbarButtonConfig;
  sound?: ToolbarButtonConfig;
  soundOff?: ToolbarButtonConfig;
}

const toolbarButtonsConfig = {
    close: { label: "Cancel" },
    loadImage: { isHidden: true },
    cameraSwitch: { className: "my-custom-camera-switch" },
    flash: { icon: "<svg>...</svg>" },
    flashOff: { icon: "<svg>...</svg>" },
};

const mrzScanViewConfig = {
    toolbarButtonsConfig
};

interface ToolbarButton {
  id: string;
  icon?: string;
  label?: string;
  isHidden?: boolean;
  className?: string;
}

type ToolbarButtonConfig = Partial<Omit<ToolbarButton, "id">>;

interface ToolbarButtonConfig {
  icon?: string;
  label?: string;
  className?: string;
  isHidden?: boolean;
}

interface FormatSelectorConfig {
  passportLabel?: string;
  idLabel?: string;
  visaLabel?: string;
  allLabel?: string;
}

const formatSelectorConfig = {
    passportLabel: "Passport",
    idLabel: "ID Card",
    visaLabel: "Visa",
    allLabel: "All",
};

const mrzScanViewConfig = {
    showFormatSelector: true,
    formatSelectorConfig
};

interface MessagesConfig {
  positionMRZ?: string;
  holdSteady?: string;
  scanSuccess?: string;
  flipDocument?: string;
  flipDocumentCountdown?: string;
  positionPortrait?: string;
  scanMRZFirst?: string;
  scanningPortrait?: string;
  portraitScanned?: string;
  bothSidesScanned?: string;
  skipPortraitLabel?: string;
  loadImageFailed?: string;
  cameraAccessDenied?: string;
}

const messagesConfig = {
    positionMRZ: "Position the MRZ inside the frame",
    scanSuccess: "Scan complete",
    flipDocument: "Flip the document over",
    flipDocumentCountdown: "Flipping in {seconds}s...",
    cameraAccessDenied: "Please grant camera permission to continue",
};

const mrzScanViewConfig = {
    messagesConfig
};

interface ThemeConfig {
  colors?: {
    primary?: string;
    accent?: string;
    backgroundDark?: string;
    backgroundOverlay?: string;
    backgroundSkipLabel?: string;
    text?: string;
    textSecondary?: string;
    divider?: string;
    guideFrame?: string;
    spinnerColor?: string;
    spinnerBackground?: string;
  };

  typography?: {
    fontFamily?: string;
    formatBtnFontSize?: string;
    formatBtnFontSizeSmall?: string;
  };

  spacing?: {
    topBarHeight?: string;
    topBarHeightDesktop?: string;
    guideFrameWidth?: string;
    guideFrameWidthDesktop?: string;
  };
}

const themeConfig = {
    colors: {
        primary: "#0066cc",
        accent: "#00aaff",
        backgroundDark: "#1a1a1a",
        text: "#ffffff",
        guideFrame: "#ffffff",
    },
    typography: {
        fontFamily: "'Inter', sans-serif",
        formatBtnFontSize: "13px",
    },
    spacing: {
        topBarHeight: "56px",
        guideFrameWidth: "85%",
    },
};

const mrzScanViewConfig = {
    themeConfig
};

interface MRZResult {
  status?: EnumResultStatus;
  data?: MRZData;

  getDocumentImage(side: EnumDocumentSide): MRZImage | null;
  getOriginalImage(side: EnumDocumentSide): MRZImage | null;
  getPortraitImage(): MRZImage | null;
}

(async () => {
    // Launch the scanner and wait for the result
    const result = await mrzScanner.launch();
    console.log(result.status); // prints the result status code to the console
    console.log(result.data); // prints the entire MRZData object to the console

    // Render the cropped document and portrait images
    const documentImage = result.getDocumentImage(Dynamsoft.EnumDocumentSide.MRZ);
    const portraitImage = result.getPortraitImage();
    if (documentImage) document.body.appendChild(documentImage.toCanvas());
    if (portraitImage) document.body.appendChild(portraitImage.toCanvas());
})();

interface MRZImage extends DSImageData {
  toCanvas(): HTMLCanvasElement;
  toBlob(): Promise<Blob>;
}

const documentImage = result.getDocumentImage(Dynamsoft.EnumDocumentSide.MRZ);
if (documentImage) {
    // Render to the DOM
    document.body.appendChild(documentImage.toCanvas());

    // Or upload to a server
    const blob = await documentImage.toBlob();
    await fetch("/upload", { method: "POST", body: blob });
}

interface MRZData {
  [EnumMRZData.InvalidFields]?: EnumMRZData[]; // invalidFields
  [EnumMRZData.DocumentType]: EnumCodeType; // documentType
  [EnumMRZData.DocumentNumber]: string; // documentNumber
  [EnumMRZData.MRZText]: string; // mrzText
  [EnumMRZData.FirstName]: string; // firstName
  [EnumMRZData.LastName]: string; // lastName
  [EnumMRZData.Age]: number; // age
  [EnumMRZData.Sex]: string; // sex
  [EnumMRZData.IssuingState]: string; // issuingState
  [EnumMRZData.IssuingStateRaw]: string; // issuingStateRaw
  [EnumMRZData.Nationality]: string; // nationality
  [EnumMRZData.NationalityRaw]: string; // nationalityRaw
  [EnumMRZData.DateOfBirth]: MRZDate; // dateOfBirth
  [EnumMRZData.DateOfExpiry]: MRZDate; // dateOfExpiry
  [EnumMRZData.OptionalData1]?: string; // optionalData1
  [EnumMRZData.OptionalData2]?: string; // optionalData2
}

(async () => {
    // Launch the scanner and wait for the result
    const result = await mrzScanner.launch();
    console.log(result.data.firstName); // prints the first name
    console.log(result.data.lastName); // prints the last name
    console.log(result.data.sex); // prints the sex
    console.log(result.data.nationality); // prints the nationality
    console.log(result.data.documentNumber); // prints the document number
})();

interface MRZDate {
  year: number;
  month: number;
  day: number;
}

(async () => {
    // Launch the scanner and wait for the result
    const result = await mrzScanner.launch();
    console.log(result.data.dateOfBirth.year); // prints the year of the date of birth
    console.log(result.data.dateOfBirth.month); // prints the month of the date of birth
    console.log(result.data.dateOfBirth.day); // prints the day of the date of birth
})();

type ResultStatus = {
  code: EnumResultStatus;
  message?: string;
};

function displayMRZDate(date: MRZDate): string

const dob = Dynamsoft.displayMRZDate(result.data.dateOfBirth);
console.log(dob); // e.g. "1992-04-15"

const MRZDataLabel: Record<EnumMRZData, string>

Object.entries(result.data).forEach(([key, value]) => {
    const label = Dynamsoft.MRZDataLabel[key];
    console.log(`${label}: ${value}`);
});