Barcode Scanner JavaScript Edition API Reference
BarcodeScanner is a ready-to-use class that combines barcode decoding with camera control and UI. Add barcode scanning to your web app with just a few lines of code—camera access, viewfinder rendering, and lifecycle management are all handled for you.
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;
}
license
The license key to activate the barcode scanner.
Type: string
scanMode
Defines the scan mode of the BarcodeScanner.
Type: EnumScanMode
Default: SM_SINGLE
templateFilePath
Path to a CaptureVisionTemplate file used for barcode reading.
Type: string
utilizedTemplateNames
Defines template names mapped to scanning modes.
Type: UtilizedTemplateNames
Default: {"single": "ReadBarcodes_SpeedFirst", "multi_unique": "ReadBarcodes_SpeedFirst", "image": "ReadBarcodes_ReadRateFirst"}
engineResourcePaths
Paths to engine resources like WASM or workers. See EngineResourcePaths for details.
Type: EngineResourcePaths
uiPath
Path to the custom UI (.xml template file) for the ScannerView.
Type: string
barcodeFormats
Specifies the barcode formats to recognize. See EnumBarcodeFormat.
Type: EnumBarcodeFormat | Array<EnumBarcodeFormat>
duplicateForgetTime
Time in milliseconds before a barcode (same format + text) can trigger onUniqueBarcodeScanned again.
Type: number
Default: 3000
showPoweredByDynamsoft
Whether to show the “powered by” message.
Type: boolean
Default: true
autoStartCapturing
Whether to start capturing directly after opening the camera.
Type: boolean
Default: true
container
A container element or selector for rendering the scanner and/or result view.
Type: HTMLElement | string
showResultView
Whether to display a result view in SM_MULTI_UNIQUE mode.
Type: boolean
Default: true
showUploadImageButton
Determines the visibility of the “uploadImage” button that allows the user to upload an image for decoding.
Type: boolean
Default: false
scannerViewConfig
Configuration for the scanner view.
Type: ScannerViewConfig
resultViewConfig
Configuration for the result view (only valid in SM_MULTI_UNIQUE).
Type: ResultViewConfig
onUniqueBarcodeScanned
A callback triggered when a unique barcode (by format + text) is scanned. Only valid in SM_MULTI_UNIQUE mode.
Type: (result: BarcodeResultItem) => void | Promise<void>
onInitPrepare
A callback function that is triggered before the scanner components are initialized.
Type: () => void
onInitReady
Called when the scanner components have been successfully initialized and are ready.
Type: (components: {cameraView: CameraView; cameraEnhancer: CameraEnhancer; cvRouter: CaptureVisionRouter}) => void
onCameraOpen
Called when the camera is successfully opened for the first time or after each camera switch.
Type: (components: {cameraView: CameraView; cameraEnhancer: CameraEnhancer; cvRouter: CaptureVisionRouter}) => void
onCaptureStart
Called when the capture process begins.
Type: (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;
}
container
A dedicated container for the ScannerView (video stream).
Type: HTMLElement | string | undefined
showCloseButton
Determines the visibility of the “closeButton” button that allows the user to close the ScannerView.
Type: boolean
Default: true
mirrorFrontCamera
Whether to mirror the camera feed when using the front-facing camera.
Type: boolean
Default: true
cameraSwitchControl
Specifies the mode and visibility of the camera switch control, enabling users to change between cameras. See CameraSwitchControlMode.
Type: CameraSwitchControlMode
Default: "hidden"
showFlashButton
Controls the visibility of the “Flash” button that lets the user toggle the camera’s torch.
Type: boolean
Default: false
customHighlightForBarcode
A callback function that allows customization of the visual highlight for detected barcodes. See DrawingItem.
Type: (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
};
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;
}
container
A dedicated container for the ResultView.
Type: HTMLElement | string | undefined
toolbarButtonsConfig
Configures the main bottom toolbar of the ResultView.
Type: 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;
}
clear
Configuration for the clear button of the toolbar.
Type: ToolbarButtonConfig
done
Configuration for the done button of the toolbar.
Type: 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;
}
label
The text label of the button.
Type: string
className
Assigns a custom class to the button (usually to apply custom styling).
Type: string
isHidden
Hides/Shows the button in the toolbar.
Type: 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;
}
status
The status of the barcode scanning, which can be success, cancelled, or failed (indicating that something has gone wrong during the scanning process).
Type: ResultStatus
barcodeResults
An array of BarcodeResultItem representing the decoded barcode(s).
Type: Array<BarcodeResultItem>
originalImageResult
A DSImageData object that represents the original image of the successfully decoded barcode.
Type: DSImageData
barcodeImage
A DSImageData object containing the cropped barcode image.
Type: 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;
}
single
Template name used for single barcode scanning mode.
Type: string
multi_unique
Template name used for scanning multiple unique barcodes.
Type: string
image
Template name used when barcode scanning is based on a provided image input.
Type: 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
}
Yes
No