Barcode Scanner JavaScript Edition API Reference

BarcodeScanner is a configurable barcode scanning module featuring a pre-built UI that supports both live camera and still image decoding. Designed for effortless integration into web applications, it offers a ready-to-use, customizable interface to streamline barcode scanning implementation.

Constructor

BarcodeScanner

new BarcodeScanner(config?: BarcodeScannerConfig)

Parameters

config (optional): Assigns the license and configures the different settings of the BarcodeScanner, including the container, supported barcode formats, and more. This config object is of type BarcodeScannerConfig.

Code Snippet

const barcodeScanner = new Dynamsoft.BarcodeScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  scannerViewConfig: {
  //  container: "#camera-view-container",
  },
  // showUploadImageButton: true,
  // scanMode: Dynamsoft.EnumScanMode.SM_MULTI_UNIQUE,
});

Methods

launch()

Launches the scanner and optionally renders the scanning UI based on scanMode and container configuration.

launch(): Promise<BarcodeScanResult>

Returns

A promise that resolves to a BarcodeScanResult.

Code Snippet

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

dispose()

Disposes the scanner instance and cleans up all related resources.

dispose(): void

Code Snippet

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

decode()

Decodes a barcode from an image, URL, or canvas element.

decode(imageOrFile: Blob | string | DSImageData | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement,templateName?: string): Promise<CapturedResult>

Parameters

imageOrFile: The input image source.

templateName (optional): The name of the CaptureVisionTemplate to be used.

Returns

A promise that resolves to a CapturedResult.

Code Snippet

const imageUrl = 'https://example.com/image.png';
const results = barcodeScanner.decode(imageUrl);
//... do something with the results

Interfaces

BarcodeScannerConfig

Configuration options for initializing a BarcodeScanner.

interface BarcodeScannerConfig {
  license?: string;
  scanMode?: EnumScanMode;
  templateFilePath?: string;
  utilizedTemplateNames?: UtilizedTemplateNames;
  engineResourcePaths?: EngineResourcePaths;
  uiPath?: string;
  barcodeFormats?: EnumBarcodeFormat | Array<EnumBarcodeFormat>;
  duplicateForgetTime?: number;
  showPoweredByDynamsoft?: boolean;
  autoStartCapturing? : boolean;
  container?: HTMLElement | string | undefined;
  onUniqueBarcodeScanned?: (result: BarcodeResultItem) => void | Promise<void>;
  showResultView?: boolean;
  showUploadImageButton?: boolean;
  scannerViewConfig?: ScannerViewConfig;
  resultViewConfig?: ResultViewConfig;
  onInitPrepare?: () => void;
  onInitReady?: (components: {cameraView: CameraView;cameraEnhancer: CameraEnhancer;cvRouter: CaptureVisionRouter;}) => void;
  onCameraOpen?: (components: {cameraView: CameraView;cameraEnhancer: CameraEnhancer;cvRouter: CaptureVisionRouter;}) => void;
  onCaptureStart?: (components: {cameraView: CameraView;cameraEnhancer: CameraEnhancer;cvRouter: CaptureVisionRouter;}) => void;
}

Code Snippet

<div id="camera-view-container" style="width: 100%; height: 80vh"></div>
<script>
  const barcodeScannerConfig = {
    license: "YOUR_LICENSE_KEY_HERE",
    // Defines scan behavior:
    //   - SM_MULTI_UNIQUE: Keeps scanning and continuously collecting unique decoded barcode results.
    //   - SM_SINGLE: Scans once a result is found.
    scanMode: Dynamsoft.EnumScanMode.SM_MULTI_UNIQUE,
    // The path to your custom JSON template that defines the scanning process.
    templateFilePath:'./DBR-PresetTemplates.json',
    // engineResourcePaths typically is only assigned when using a framework like React/Angular/Vue where the resources are not in the same location as the script reference.
    engineResourcePaths: {rootDirectory:"https://cdn.jsdelivr.net/npm/"},
    // path to the UI file
    uiPath: "https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@11.2.4000/dist/ui/barcode-scanner.ui.xml",
    barcodeFormats: [Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE , Dynamsoft.DBR.EnumBarcodeFormat.BF_CODE_128],
    showPoweredByDynamsoft: false,
    duplicateForgetTime: 3000,
    showUploadImageButton: true,
    autoStartCapturing: true,
    // The container for rendering the scanner and/or result view. Note that ResultView is only valid for SM_MULTI_UNIQUE mode. If not specified, a full-viewport default UI will be created.
    container: "#camera-view-container",
    scannerViewConfig: {
      // The ScannerViewConfig goes in here - see ScannerViewConfig section
    },
    resultViewConfig: {
      // The ResultViewConfig goes in here - see ResultViewConfig section
    },
    onUniqueBarcodeScanned: (result) => {
      // Do something with the result
    },
    onInitPrepare: () => {
      // Do something before the barcodeScanner initialized
    },
    onInitReady: (components) => {
      // Do something with the foundational components
      // Set the scan laser to be visible in cameraView
      components.cameraView.setScanLaserVisible(true);
      // Set the zoom factor to 3
      components.cameraEnhancer.setZoom({
         factor: 3
      });
      // Set the scan region to a rectangle with percentage values by cameraEnhancer
      let region = {
        "x": 0,
        "y": 20,
        "width": 100,
        "height": 60,
        "isMeasuredInPercentage": true
      };
      components.cameraEnhancer.setScanRegion(region);
    },
    onCameraOpen: (components) => {
      // Do something with the foundational components when the camera is successfully opened for the first time or after each camera switch
    },
    onCaptureStart: (components) => {
      // Do something with the foundational components when the capture process begins
    },
  };
  // Initialize the BarcodeScanner with the above BarcodeScannerConfig object
  const barcodeScanner = new Dynamsoft.BarcodeScanner(barcodeScannerConfig);
</script>

ScannerViewConfig

The ScannerViewConfig is used to configure the UI elements of the BarcodeScannerView. If the ScannerViewConfig is not assigned, then the library will use the default BarcodeScannerView.

interface ScannerViewConfig {
  container?: HTMLElement | string | undefined;
  showCloseButton?: boolean;
  mirrorFrontCamera?: boolean;
  cameraSwitchControl?: CameraSwitchControlMode;
  showFlashButton?: boolean;
  customHighlightForBarcode?: (result: BarcodeResultItem) => DrawingItem;
}

Code Snippet

const barcodeScannerViewConfig = {
  // Hide the close button that shows up at the top right of the view
  showCloseButton: false, 
  // Show the flash button that lets the user toggle the camera's torch.
  showFlashButton: true, 
  // Shows the camera switcher that can toggle between front and back cameras.
  cameraSwitchControl: "toggleFrontBack", 
  // Change the highlight style for all detected barcodes
  customHighlightForBarcode: (item) => {
      const imageDrawingStyleId = Dynamsoft.DCE.DrawingStyleManager.createDrawingStyle({
          lineWidth: 5, fillStyle: "rgba(0, 255, 255, 0.5)", strokeStyle: "rgba(0, 255, 255, 1)"
      });
      const drawingItem = new Dynamsoft.DCE.RectDrawingItem(
          {
              x: item.location.points[0].x,
              y: item.location.points[0].y,
              width: item.location.points[1].x - item.location.points[0].x,
              height: item.location.points[2].y - item.location.points[0].y,
              isMeasuredInPercentage: false
          },
          imageDrawingStyleId
      )
      return drawingItem;
  },
};

const barcodeScannerConfig = {
    license: "YOUR_LICENSE_KEY_HERE",
    scannerViewConfig: barcodeScannerViewConfig
};

See Also

• drawingItem
• CameraSwitchControlMode

ResultViewConfig

The ResultViewConfig is used to configure the UI elements of the BarcodeResultView. If the ResultViewConfig is not assigned, then the library will use the default BarcodeResultView.

interface ResultViewConfig {
  container?: HTMLElement | string | undefined;
  toolbarButtonsConfig?: BarcodeResultViewToolbarButtonsConfig;
}

Code Snippet

const barcodeResultViewConfig = {
    toolbarButtonsConfig: {
      clear: {
          label: "Clear-all", // Changes the text label of the clear button to "Clear-all"; string is "Clear" by default
          isHidden: true // Hides the clear button; false by default
      },
      done: {
          label: "Return Home", // Changes the text label of the done button to "Return Home"; string is "Done" by default
          isHidden: false // Hides the done button; false by default
      }
  },
}

const barcodeScannerConfig = {
    license: "YOUR_LICENSE_KEY_HERE",
    resultViewConfig: barcodeResultViewConfig
};

BarcodeResultViewToolbarButtonsConfig

The BarcodeResultViewToolbarButtonsConfig is used to configure the buttons of the toolbar in the BarcodeResultView.

interface BarcodeResultViewToolbarButtonsConfig {
  clear?: ToolbarButtonConfig;
  done?: ToolbarButtonConfig;
}

Code Snippet

// Default value as shown below
const barcodeScannerButtonConfig = {
    clear: {
        label: "Clear", 
        isHidden: false
    },
    done: {
        label: "Done",
        isHidden: false
    }
};

const barcodeResultViewConfig = {
    toolbarButtonsConfig: barcodeScannerButtonConfig
};

ToolbarButtonConfig

The interface used to configure the properties of the toolbar button.

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

BarcodeScanResult

The BarcodeScanResult is the most basic interface that is used to represent the full barcode scan result object. It comes with a result status, the original and cropped image result, and the detailed info of the decoded barcode(s).

interface BarcodeScanResult {
  status: ResultStatus;
  barcodeResults?: BarcodeResultItem[];
  originalImageResult?: DSImageData;
  barcodeImage?: DSImageData;
}

Code Snippet

(async () => {
    // Launch the scanner and wait for the result
    const result = await barcodeScanner.launch();
    // Prints the result status message to the console
    console.log(result.status.message); 
    // Prints the result status code to the console
    console.log(result.status.code); 
    // Prints an array containing all the decoded barcode results to the console. Note that in SM_SINGLE mode, the length of this array is 1.
    console.log(result.barcodeResults); 
})();

UtilizedTemplateNames

An object that defines the names of templates utilized by the BarcodeScanner for different scanning modes.

interface UtilizedTemplateNames {
  single: string;
  multi_unique: string;
  image: string;
}

Code Snippet

const barcodeScannerConfig = {
    //..
    utilizedTemplateNames:{
      single: `ReadBarcodes_SpeedFirst`,
      multi_unique: `ReadBarcodes_SpeedFirst`,
      image: `ReadBarcodes_ReadRateFirst`,
    }
    //..
}

Various preset templates are at your disposal for barcode reading:

Template Name	Function Description
ReadBarcodes_Default	Scans multiple barcodes by default setting.
ReadSingleBarcode	Quickly scans a single barcode.
ReadBarcodes_SpeedFirst	Prioritizes speed in scanning multiple barcodes.
ReadBarcodes_ReadRateFirst	Maximizes the number of barcodes read.
ReadBarcodes_Balance	Balances speed and quantity in reading multiple barcodes.
ReadDenseBarcodes	Specialized in reading barcodes with high information density.
ReadDistantBarcodes	Capable of reading barcodes from extended distances.

ResultStatus

ResultStatus is used to represent the status of the barcode scanning result. This status can be success, cancelled if the user closes the scanner during scanning, or failed if something went wrong during the scanning process. The code of the result status is a EnumResultStatus.

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

Types

CameraSwitchControlMode

• "hidden": Hides the camera switch control entirely. Users will not be able to switch cameras manually.

• "listAll": List all available cameras (e.g., front, back, external cameras).

• "toggleFrontBack": Allows toggling only between the front and back cameras.

type CameraSwitchControlMode = "hidden" | "listAll" | "toggleFrontBack";

Enums

EnumScanMode

enum EnumScanMode {
    SM_SINGLE = 0,
    SM_MULTI_UNIQUE = 1
}

EnumResultStatus

enum EnumResultStatus {
    RS_SUCCESS = 0,
    RS_CANCELLED = 1,
    RS_FAILED = 2
}