`<bmx-barcode-scanner>`

A form field for a barcode value. Type it, let a hand-held scanner type it (they behave as a keyboard and press Enter), or - in browsers with a built-in barcode reader - scan it with the camera or from a picture.

16 properties · 3 events · 7 methods · 6 parts

Example

Nothing scanned yet.

Something to scan

Show markup

<bmx-barcode-scanner id="ex-scan" label="Product code" placeholder="Scan or type a code" description="A hand-held scanner works anywhere. Where the browser can read barcodes, the camera and picture buttons appear too." formats="ean13, ean8, upca, code128, qr, datamatrix"></bmx-barcode-scanner>
<p class="note" id="ex-scan-out" role="status">Nothing scanned yet.</p>

<h3>Something to scan</h3>

<div class="row" style="gap: 24px; flex-wrap: wrap; align-items: flex-end">
  <bmx-barcode type="ean13" value="5012345678900"></bmx-barcode>
  <bmx-qr-code value="BMX-SCAN-TEST" size="120"></bmx-qr-code>
</div>

<script type="module">
  await customElements.whenDefined('bmx-barcode-scanner');
  const scanner = document.getElementById('ex-scan');
  const out = document.getElementById('ex-scan-out');
  scanner.addEventListener('bmxBarcodeScan', e => {
    const { value, format, source } = e.detail;
    out.textContent = `${source === 'keyboard' ? 'Entered' : 'Scanned'} ${value}${format ? ` (${format})` : ''} from the ${source}.`;
  });
  if (!(await scanner.canScan())) out.textContent = 'This browser has no barcode reader, so the field takes typing and hand-held scanners.';
</script>

NOTHING LEAVES THE DEVICE

The camera picture is read by the browser's own barcode reader, in the page, frame by frame; no image is kept, stored or sent anywhere, and the camera is switched off as soon as a code is read or the panel is closed.

WHERE THE CAMERA IS OFFERED

Only where the browser has a barcode reader (BarcodeDetector): Chrome and Edge on Android and macOS, and Chromium elsewhere where the system has one. Elsewhere the buttons are not shown and the field is a typing and hand-held-scanner field, which is what most counters and warehouses use anyway.

ACCESSIBILITY

A labelled text field first; the camera and picture buttons are ordinary buttons, and what they find (or fail to) is announced.

Properties

Property	Attribute	Type	Default	Description
`camera`	`camera`	`boolean`	`true`	Offer the camera and picture buttons where the browser can read barcodes.
`description`	`description`	`string`	—
`disabled`	`disabled`	`boolean`	`false`
`errorText`	`error-text`	`string`	—	An error supplied by the page: an unknown product, for example.
`formats`	`formats`	`string[] \| string`	—	Which kinds of code to look for: names as `bmx-barcode` uses them (`qr, ean13, code128`...), or the browser's own. Default: every kind it knows.
`hideLabel`	`hide-label`	`boolean`	`false`
`label`	`label`	`string`	—
`messages`	property only	`BmxFieldMessages`	—
`name`	`name`	`string`	—	The field's name in the form.
`placeholder`	`placeholder`	`string`	—
`readonly`	`readonly`	`boolean`	`false`
`required`	`required`	`boolean`	`false`
`strings`	`strings`	`Partial<BmxBarcodeScannerStrings> \| string`	—	Replacements for any of the scanner's own wording (an object, or its JSON).
`submitOnEnter`	`submit-on-enter`	`boolean`	`false`	Let Enter (which hand-held scanners press after a code) send the form. Off by default, so a scan does not submit half a form.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`
`value`	`value`	`string`	`''`	The value: scanned or typed.

Events

Event	Detail	Description
`bmxBarcodeScan`	`BmxBarcodeScanDetail`	Fired when a code is read by the camera or from a picture, or entered and confirmed with Enter.
`bmxChange`	`BmxBarcodeScannerChangeDetail`	Fired when the value changes.
`bmxValidityChange`	`BmxBarcodeScannerValidityDetail`

Methods

Method	Signature	Description
`canScan`	`canScan() => Promise<boolean>`	Whether this browser can read barcodes from the camera or a picture.
`checkValidity`	`checkValidity() => Promise<boolean>`
`reportValidity`	`reportValidity() => Promise<boolean>`
`scanImage`	`scanImage(source: Blob \| ImageBitmap \| HTMLImageElement \| HTMLCanvasElement) => Promise<BmxBarcodeScanDetail \| null>`	Reads a code from a picture: a `Blob` or `File`, an `<img>`, a canvas or an `ImageBitmap`. Resolves to what was found, or null.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`
`startCamera`	`startCamera() => Promise<void>`	Turn the camera on and look for a code. Resolves once it is running (or has failed).
`stopCamera`	`stopCamera() => Promise<void>`	Turn the camera off.

Slots

Slot	Description
`description`	Rich help text, in place of the `description` property.
`label`	Rich label content, in place of the `label` property.

CSS shadow parts

Part	Description
`buttons`	The camera and picture buttons.
`description`	The help text.
`error`	The error message.
`input`	The text field.
`label`	The label.
`viewfinder`	The camera picture.

CSS custom properties

Property	Description
`--bmx-barcode-scanner-aim`	The colour of the aiming frame over the camera picture.
`--bmx-barcode-scanner-label-font-size`	The label's font size.
`--bmx-barcode-scanner-support-font-size`	Font size of the description, status and error.
`--bmx-barcode-scanner-viewfinder-height`	The height of the camera picture. Default 15rem.