ng-code-scanner

ng-code-scanner# NgCodeScanner

Angular library for barcode and QR code scanning. A modern Angular wrapper for html5-qrcode with Signal-based state management and full TypeScript support.This project was generated using Angular CLI version 20.3.0.

Features## Code scaffolding

• ✅ Modern Angular 20+: Built with signals, standalone components, and latest Angular featuresAngular CLI includes powerful code scaffolding tools. To generate a new component, run:

• ✅ Multiple Barcode Formats: QR Code, EAN, UPC, Code 128, and more

• ✅ Camera Selection: Choose between multiple cameras on the device```bash

• ✅ File Scanning: Scan codes from image filesng generate component component-name

• ✅ Reactive State Management: Signal-based state with computed properties```

• ✅ TypeScript: Full type safety and IntelliSense support

• ✅ Customizable: Extensive configuration optionsFor a complete list of available schematics (such as components, directives, or pipes), run:

• ✅ Responsive: Works on desktop and mobile devices

## Installationng generate --help

npm install ng-code-scanner html5-qrcode## Building

To build the library, run:

Quick Start

### Import the Componentng build ng-code-scanner

import { Component } from '@angular/core';This command will compile your project, and the build artifacts will be placed in the `dist/` directory.

import { CodeScannerComponent, ScanResult } from 'ng-code-scanner';

### Publishing the Library

@Component({

  selector: 'app-root',Once the project is built, you can publish your library by following these steps:

  imports: [CodeScannerComponent],

  template: `1. Navigate to the `dist` directory:

    <ncs-code-scanner   ```bash

      [autoStart]="true"   cd dist/ng-code-scanner

      (scanSuccess)="onScanSuccess($event)">   ```

    </ncs-code-scanner>

  `2. Run the `npm publish` command to publish your library to the npm registry:

})   ```bash

export class AppComponent {   npm publish

  onScanSuccess(result: ScanResult) {   ```

    console.log('Scanned:', result.decodedText);

  }## Running unit tests

}

```To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:



### Advanced Configuration```bash

ng test

```typescript```

import { Component, signal } from '@angular/core';

import { CodeScannerComponent, ScannerConfig, Html5QrcodeSupportedFormats } from 'ng-code-scanner';## Running end-to-end tests



@Component({For end-to-end (e2e) testing, run:

  selector: 'app-scanner',

  imports: [CodeScannerComponent],```bash

  template: `ng e2e

    <ncs-code-scanner```

      [config]="scannerConfig()"

      [cameraId]="selectedCamera()"Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.

      [showCameraSelection]="true"

      [showControls]="true"## Additional Resources

      (scanSuccess)="onScanSuccess($event)"

      (scanError)="onScanError($event)"For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.

      (scanStarted)="onScanStarted()"
      (scanStopped)="onScanStopped()">
    </ncs-code-scanner>
  `
})
export class ScannerComponent {
  protected readonly selectedCamera = signal<string | undefined>(undefined);
  protected readonly scannerConfig = signal<ScannerConfig>({
    fps: 10,
    qrbox: 250,
    formatsToSupport: [
      Html5QrcodeSupportedFormats.QR_CODE,
      Html5QrcodeSupportedFormats.EAN_13,
      Html5QrcodeSupportedFormats.CODE_128
    ],
    showTorchButtonIfSupported: true, // Show torch button on supported devices
    aspectRatio: 1.0
  });

  onScanSuccess(result: ScanResult) {
    console.log('Scanned successfully:', result.decodedText);
  }

  onScanError(error: string) {
    console.error('Scan error:', error);
  }

  onScanStarted() {
    console.log('Scanner started');
  }

  onScanStopped() {
    console.log('Scanner stopped');
  }
}

Using the Service Directly

import { Component, inject, signal } from '@angular/core';
import { CodeScannerService, ScannerConfig } from 'ng-code-scanner';

@Component({
  selector: 'app-custom-scanner',
  template: `
    <div id="scanner"></div>
    <button (click)="startScan()">Start</button>
    <button (click)="stopScan()">Stop</button>
    
    @if (scannerService.isScanning()) {
      <p>Scanning...</p>
    }
    
    @if (scannerService.lastScanResult()) {
      <p>Result: {{ scannerService.lastScanResult()?.decodedText }}</p>
    }
  `
})
export class CustomScannerComponent {
  protected readonly scannerService = inject(CodeScannerService);

  async startScan() {
    await this.scannerService.startScanning(
      'scanner',
      undefined,
      { fps: 10, qrbox: 250 },
      (result) => console.log('Scanned:', result.decodedText)
    );
  }

  async stopScan() {
    await this.scannerService.stopScanning();
  }
}

File Scanning

import { Component, inject, signal } from '@angular/core';
import { CodeScannerService } from 'ng-code-scanner';

@Component({
  selector: 'app-file-scanner',
  template: `
    <input 
      type="file" 
      accept="image/*" 
      (change)="onFileSelected($event)">
    
    @if (result()) {
      <p>Scanned: {{ result() }}</p>
    }
  `
})
export class FileScannerComponent {
  private readonly scannerService = inject(CodeScannerService);
  protected readonly result = signal<string | null>(null);

  async onFileSelected(event: Event) {
    const input = event.target as HTMLInputElement;
    const file = input.files?.[0];
    
    if (file) {
      try {
        const scanResult = await this.scannerService.scanFile(file);
        this.result.set(scanResult.decodedText);
      } catch (error) {
        console.error('Failed to scan file:', error);
      }
    }
  }
}

API Reference

CodeScannerComponent

Inputs

Input	Type	Default	Description
config	ScannerConfig	{}	Scanner configuration options
cameraId	string | undefined	undefined	Specific camera device ID
preferredFacingMode	'user' | 'environment'	'environment'	Preferred camera facing mode (front/back)
autoStart	boolean	false	Start scanning automatically
showCameraSelection	boolean	true	Show camera selection dropdown
showControls	boolean	true	Show start/stop buttons
customClass	string	''	Custom CSS class

Outputs

Output	Type	Description
scanSuccess	ScanResult	Emitted on successful scan
scanError	string	Emitted on error
scanStarted	void	Emitted when scanning starts
scanStopped	void	Emitted when scanning stops

ScannerConfig

interface ScannerConfig {
  fps?: number;                              // Frames per second (default: 10)
  qrbox?: number | { width: number; height: number }; // Scan box size (default: 250)
  formatsToSupport?: Html5QrcodeSupportedFormats[];  // Barcode formats to scan
  verbose?: boolean;                         // Enable verbose logging
  aspectRatio?: number;                      // Video aspect ratio
  disableFlip?: boolean;                     // Disable mirror effect
  videoConstraints?: MediaTrackConstraints;  // Camera constraints
  showTorchButtonIfSupported?: boolean;      // Show torch button if available
}

Supported Formats

• QR_CODE
• AZTEC
• CODABAR
• CODE_39, CODE_93, CODE_128
• DATA_MATRIX
• EAN_13, EAN_8
• UPC_A, UPC_E
• PDF_417
• ITF
• And more...

Styling

The component comes with default styles that can be customized:

/* Override default styles */
.ncs-scanner-container {
  max-width: 600px;
}

.ncs-btn-start {
  background-color: #your-color;
}

.ncs-scanner-view {
  border-radius: 12px;
}

Container Sizing

The scanner component is designed to fit exactly to the width and height of its parent container without overflow. To ensure proper sizing:

<!-- Define a container with specific dimensions -->
<div style="width: 500px; height: 400px;">
  <ncs-code-scanner [autoStart]="true"></ncs-code-scanner>
</div>

Or with CSS:

.scanner-wrapper {
  width: 100%;
  height: 500px; /* Or use vh units: height: 80vh; */
}

<div class="scanner-wrapper">
  <ncs-code-scanner [autoStart]="true"></ncs-code-scanner>
</div>

Important Notes:

• The parent container must have an explicit height defined
• The component will automatically adapt to fill 100% of the parent's width and height
• Video will use object-fit: contain to maintain aspect ratio without distortion
• All content (camera selector, controls, error messages) will fit within the container without overflow

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers with camera access

Requirements

• Angular 20+
• html5-qrcode 2.3.8+

Development

Build the library

ng build ng-code-scanner

Run tests

ng test ng-code-scanner

Publish to npm

cd dist/ng-code-scanner
npm publish

License

MIT

Credits

Built on top of html5-qrcode by Minhaz.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.