Frappe Scanner API in Frappe Framework v15
What Is the Frappe Scanner API?
The Frappe Scanner API in Frappe Framework v15 provides a unified JavaScript interface to capture barcode and QR code inputs using hardware scanners, keyboard-based scanners, or camera-based scanning. It is widely used in ERPNext for inventory, warehouse, and point-of-sale workflows.
The API is exposed through the frappe.ui.Scanner class.
Who Should Use the Frappe Scanner API?
Target Audience
- ERPNext Developers
- Warehouse & Inventory Solution Architects
- Frappe Framework Developers
- ERP Implementation Consultants
Technical Prerequisites
- Frappe Framework v15
- JavaScript (ES6)
- Understanding of ERPNext stock workflows
How Does frappe.ui.Scanner Work?
The Scanner API listens for scan input and triggers callback functions when a barcode or QR code is detected. It abstracts scanner detection logic so developers do not need to differentiate between hardware scanners and camera-based input.
Core Entity: frappe.ui.Scanner
Module: Desk
Source File (v15): frappe/public/js/frappe/ui/scanner.js
How to Enable Scanning in Frappe Framework v15?
Basic Scanner Example
frappe.ui.Scanner.scan({
on_scan: function (scan_data) {
console.log(scan_data);
}
});
What this does:
This activates the scanner and captures scanned data, returning the scanned string through the on_scan callback.
What Data Does the Scanner Return?
The scanner returns a string value representing the scanned barcode or QR code. The API does not parse or validate the value automatically. Validation must be handled by the consuming logic.
on_scan: function (data) {
// data is the scanned code
}
How to Use Scanner in ERPNext Forms?
The Scanner API is commonly used inside Client Scripts or custom buttons.
frm.add_custom_button('Scan Item', () => {
frappe.ui.Scanner.scan({
on_scan(data) {
frm.set_value('barcode', data);
}
});
});
This enables seamless barcode capture directly into DocType fields.
Common ERPNext Use Cases for Scanner API
Industry Relevance
- Manufacturing: Raw material identification
- Warehousing: Bin-level stock movement
- Retail: POS barcode scanning
- Logistics: Package and shipment tracking
The Scanner API reduces manual entry errors and improves transaction speed.
Best Practices for Using Frappe Scanner API
- Always validate scanned values against DocTypes
- Avoid triggering multiple scanners simultaneously
- Provide clear UI prompts for users
- Combine with sound or visual feedback for success/failure
- Handle empty or invalid scans gracefully
Troubleshooting Common Scanner Issues
Scanner Not Triggering
- Ensure the page is focused
- Verify browser permissions for camera access
- Confirm frappe.ui.Scanner.scan() is called
Incorrect Data Captured
- Trim whitespace from scanned input
- Validate against expected barcode formats
- Confirm scanner configuration
Advanced Usage Patterns
Conditional Scan Handling
frappe.ui.Scanner.scan({
on_scan(data) {
if (!data) return;
frappe.msgprint(`Scanned Code: ${data}`);
}
});
This pattern ensures clean handling of invalid or empty scans.
Integration Patterns
The Scanner API integrates seamlessly with:
- Stock Entry
- Delivery Note
- POS Invoice
- Custom Warehouse Apps
- ERPNext Inventory Module
It is frequently paired with frappe.call for server-side validation.
Cross-References
- ERPNext Stock Module
- Frappe Client Scripts
- Frappe Form API
- ERPNext POS
Official References (Verified)
Scanner API Docs (v15):
https://docs.frappe.io/framework/user/en/api/scanner
GitHub Source (v15):
