kasif-mrz

React component for MRZ (Machine Readable Zone) scanning and parsing from passport/ID card images. Uses Web Workers for non-blocking processing.

🔗 Live Demo

Features

• 📷 File input — Upload passport/ID images for MRZ extraction
• 🔍 MRZ Parser — Supports TD1 (ID cards), TD3 (Passports) formats
• ⚡ Web Workers — Non-blocking image processing
• 🎨 Customizable — Pass custom children, className, styles
• 📦 TypeScript — Full type definitions included
• 🪶 Lightweight — Zero runtime dependencies

Install

npm install kasif-mrz

Usage

Basic

import { MrzScanner } from 'kasif-mrz';

function App() {
  return (
    <MrzScanner
      onResult={(result) => {
        console.log(result);
        // { documentType, countryCode, lastName, firstName, documentNumber, ... }
      }}
      onError={(err) => console.error(err)}
    />
  );
}

With custom UI

import { MrzScanner } from 'kasif-mrz';

function App() {
  const [result, setResult] = useState(null);

  return (
    <div>
      <MrzScanner onResult={setResult} className="scanner-wrapper">
        <label className="custom-upload-btn">
          📷 Scan Passport
          <input type="file" accept="image/*" hidden />
        </label>
      </MrzScanner>

      {result && (
        <div>
          <p>Name: {result.firstName} {result.lastName}</p>
          <p>Document: {result.documentNumber}</p>
          <p>Nationality: {result.nationality}</p>
        </div>
      )}
    </div>
  );
}

Parse MRZ text directly

import { parseMrz } from 'kasif-mrz';

const result = parseMrz(
  'P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<\n' +
  'L898902C36UTO7408122F1204159ZE184226B<<<<<10'
);

console.log(result);
// {
//   documentType: 'P',
//   countryCode: 'UTO',
//   lastName: 'ERIKSSON',
//   firstName: 'ANNA MARIA',
//   documentNumber: 'L898902C3',
//   nationality: 'UTO',
//   dateOfBirth: '740812',
//   sex: 'F',
//   expirationDate: '120415',
//   valid: true
// }

API

<MrzScanner /> Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | onResult | (result: MrzResult) => void | required | Called with parsed MRZ data | | onError | (error: Error) => void | — | Called on errors | | onProgress | (progress: number) => void | — | Progress callback (0-100) | | accept | string | 'image/*' | File input accept attribute | | className | string | — | Wrapper class name | | style | CSSProperties | — | Wrapper inline styles | | children | ReactNode | — | Custom file input UI |

MrzResult Interface

interface MrzResult {
  raw: string;
  documentType?: string;    // 'P' (passport), 'I' (ID), etc.
  countryCode?: string;     // Issuing country (3-letter)
  lastName?: string;
  firstName?: string;
  documentNumber?: string;
  nationality?: string;     // 3-letter country code
  dateOfBirth?: string;     // YYMMDD format
  sex?: string;             // 'M', 'F', or '<'
  expirationDate?: string;  // YYMMDD format
  valid: boolean;           // Whether MRZ was successfully parsed
}

parseMrz(text: string): MrzResult

Standalone function to parse MRZ text without the React component.

Supported Formats

| Format | Lines | Chars/Line | Document Type | |--------|-------|-----------|---------------| | TD3 | 2 | 44 | Passports | | TD1 | 3 | 30 | ID Cards, Visas |

License

MIT