BarcodeScannerField - Filament Flex Fields

Added in v2.6.0

Summary

Barcode and QR input on the FlexTextInput shell with a Filament modal camera scanner, optional manual typing, format whitelist, and EAN/UPC checksum validation. Uses a hybrid scan engine: native BarcodeDetector when the browser supports it (Chrome/Edge), with automatic ZXing fallback. On a successful scan the field fills the input, plays a confirmation sound, and closes the modal (unless continuous() is enabled).


Class	`Bjanczak\FilamentFlexFields\Filament\Forms\Components\BarcodeScannerField`
State type	`string\|null` — scanned or typed barcode value (symbology is not stored)
Model cast	`'sku' => 'string'` (typical)
FieldType	(no dedicated FieldType mapping yet — use the class directly)
Playground	`barcode-scanner-field` slug in Flex Fields playground

Basic usage

use Bjanczak\FilamentFlexFields\Filament\Forms\Components\BarcodeScannerField;

BarcodeScannerField::make('sku')
    ->label('Product barcode')
    ->placeholder('Scan or type barcode…')
    ->required();

Filament resource example:

use Filament\Forms\Form;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\BarcodeScannerField;
use Bjanczak\FilamentFlexFields\Enums\BarcodeFormat;

public static function form(Form $form): Form
{
    return $form->schema([
        BarcodeScannerField::make('ean')
            ->label('EAN barcode')
            ->formats([BarcodeFormat::Ean13, BarcodeFormat::Ean8])
            ->validateChecksum()
            ->allowManualInput(false)
            ->helperText('Scan the product barcode with your camera.')
            ->columnSpanFull(),
    ]);
}

State format

The field stores a plain string (or null when empty). Whitespace is trimmed on hydrate/dehydrate.

// Valid EAN-13 example
'5901234123457'

// QR / Code128 example
'SKU-WAREHOUSE-42'

The detected symbology is not persisted in state. Validation uses heuristics on the string (see Format detection).

Supported formats

Configure allowed symbologies with formats() or supportedFormats(). When omitted, all built-in formats are allowed.

Enum case	Slug	Typical use	Example test value
`BarcodeFormat::Qr`	`qr`	QR codes, tickets, URLs	`https://example.com/t/abc`
`BarcodeFormat::Ean13`	`ean_13`	Retail products (EU)	`5901234123457` ✓ checksum
`BarcodeFormat::Ean8`	`ean_8`	Small retail packages	`96385074`
`BarcodeFormat::UpcA`	`upc_a`	US retail (12 digits)	`036000291452`
`BarcodeFormat::UpcE`	`upc_e`	Compressed UPC	`042526`
`BarcodeFormat::Code128`	`code_128`	Logistics, GS1-128	`ABC-128-TEST`
`BarcodeFormat::Code39`	`code_39`	Industrial, inventory	`ABC-123`
`BarcodeFormat::Itf`	`itf`	Carton / interleaved 2 of 5	`1234567890`
`BarcodeFormat::Pdf417`	`pdf417`	IDs, boarding passes	`PDF417-DEMO-VALUE`
`BarcodeFormat::DataMatrix`	`data_matrix`	Small parts, pharma	`DM-TEST-001`

Invalid checksum example (EAN-13): 5901234123450.

Limit formats to specific symbologies

Yes — pass only the formats you need. The whitelist is applied in three places:

Camera engine — BarcodeDetector / ZXing hints (what the camera tries to decode).
Client validation — rejects scans that do not match allowed patterns before accepting.
Server validation — BarcodeValidator on form submit.

EAN / UPC only (retail)

BarcodeScannerField::make('ean')
    ->formats([
        BarcodeFormat::Ean13,
        BarcodeFormat::Ean8,
        BarcodeFormat::UpcA,
        BarcodeFormat::UpcE,
    ])
    ->validateChecksum()
    ->allowManualInput(false);

QR only

BarcodeScannerField::make('ticket_code')
    ->formats([BarcodeFormat::Qr])
    ->modalHeading('Scan ticket QR code');

Warehouse — Code 128 + ITF

BarcodeScannerField::make('pallet_id')
    ->formats([BarcodeFormat::Code128, BarcodeFormat::Itf])
    ->scanDelay(500);

Dynamic whitelist (Closure)

BarcodeScannerField::make('code')
    ->formats(fn (): array => $this->record?->requires_qr_only
        ? [BarcodeFormat::Qr]
        : [BarcodeFormat::Ean13, BarcodeFormat::Code128]);

Format detection

There are two layers:

Layer	What it does
Camera (ZXing / BarcodeDetector)	Decodes the physical symbology from the image. Respects `formats()` hints.
Validation (JS + PHP)	Checks whether the string value matches allowed patterns (regex/heuristics).

Important:

By default state is a string (value only). Enable storeDetectedFormat() to persist { value, format } from the camera engine.
Server-side matching is heuristic (e.g. 13 digits → EAN-13). Ambiguous strings may match the first allowed format in priority order (EAN before QR).
BarcodeFormat::Qr is the widest pattern — avoid combining it with numeric formats if you rely on manual typing.
validateChecksum() adds real modulo-10 verification for EAN/UPC (recommended for retail).

Scan UX

Default flow (without continuous()):

User clicks scan button → Filament modal opens.
Camera starts after the modal transition (badge shows Native engine on desktop Chrome/Edge or ZXing engine on mobile).
On valid scan → input filled, confirmation beep (when beepOnScan() is on), modal closes immediately.
Toolbar below the preview — Switch camera and Turn torch on/off (when supported); not overlaid on the video.
On mobile, switch camera toggles front ↔ rear via facingMode; on desktop, cycles MediaDeviceInfo when multiple inputs exist.
When pauseWhenHidden() is on (default), decoding pauses while the browser tab is in the background to save battery.

With continuous() — modal stays open for inventory-style scanning; input updates on each successful read.

Mobile / iOS notes

Topic	Behaviour
Camera preview	Body-mounted video portal + synced overlay so WebKit renders the stream inside the Filament modal
Switch camera	`environment` ↔ `user` facing toggle (recommended on phones)
Success sound	Short Web Audio tone — no lock-screen / Control Center “Now Playing” entry
Desktop sound	Bundled MP3 (`barcode-scan-success.mp3`) with synthesized fallback

Configuration API

All methods accept Closure for dynamic configuration.

Method	Description	Default
`formats()` / `supportedFormats()`	Allowed symbologies (`list<BarcodeFormat\|string>`)	all formats
`validateChecksum()`	Modulo-10 check for EAN/UPC	`false`
`continuous()`	Keep modal open after each scan	`false`
`beepOnScan()`	Play confirmation sound on success (MP3 on desktop; transient Web Audio on mobile)	`true`
`autoSubmit()`	Dispatch `barcode-auto-submit` + `form.requestSubmit()`	`false`
`cameraFacing('environment'\|'user')`	Preferred camera when no `preferredDeviceId()`	`environment`
`preferredDeviceId(?string)`	Pin a specific `MediaDeviceInfo.deviceId`	`null`
`allowCameraSwitch()`	Show switch-camera in toolbar (`facingMode` on mobile; cycle devices on desktop)	`true`
`scanDelay(int)`	Debounce duplicate reads (ms)	`750`
`scanInterval(int)`	Decode loop interval (ms), clamped 50–2000	`120`
`decodeFps(int)`	Shorthand for `scanInterval` via `1000 / fps`	—
`pauseWhenHidden()`	Pause decode when tab is hidden (Page Visibility API)	`true`
`storeDetectedFormat()`	State `{ value, format }` instead of plain string	`false`
`allowManualInput()`	Text input fallback	`true`
`scanButtonLabel()`	Scan button / `aria-label`	translated
`modalHeading()`	Filament modal title	translated
`scanIcon()`	Scan trigger icon	QR icon
`barcodeRule(Closure\|string)`	Extra Filament validation	none
`variant()`	`primary`, `secondary`, `soft`, `flat`, `ghost`	`primary`
`size()`	`sm`, `md`, `lg`	`md`

`placeholder(string|Closure|null $placeholder)`

Inherited from Filament HasPlaceholder. Default translation: filament-flex-fields::default.barcode_scanner.placeholder.

BarcodeScannerField::make('sku')->placeholder('Scan or type EAN…');

`readOnly(bool|Closure $condition = true)` / `disabled(bool|Closure $condition = true)`

Inherited from Filament CanBeReadOnly. Read-only keeps the scanned value visible but blocks manual edits and opening the scanner modal.

BarcodeScannerField::make('registered_sku')
    ->default(fn ($record) => $record->sku)
    ->readOnly();

`focusOutline(bool|Closure $condition = true)`

Inherited from HasFieldFocusOutline. Default: false. When true, shows the shared focus ring on the FlexTextInput shell.

BarcodeScannerField::make('sku')->focusOutline();

Public helper methods

Method	Returns	Description
`getBeepUrl()`	`string`	URL for desktop confirmation MP3
`getAlpineConfiguration()`	`array`	Full config passed to Alpine (`supportedFormats`, labels, etc.)
`getWrapperClasses()`	`array<string, bool>`	Root CSS class map

Standard Filament field methods (required(), rule(), unique(), live(), helperText(), …) work as usual.

Model & persistence

// Migration
$table->string('sku')->nullable()->unique();

// Model — plain string, no special cast
protected $fillable = ['sku'];

BarcodeScannerField::make('sku')
    ->default(fn (?Product $record): ?string => $record?->sku)
    ->formats([BarcodeFormat::Ean13])
    ->validateChecksum();

When storeDetectedFormat() is enabled, cast or accessor handling may be needed if you persist the full { value, format } array — the default string column stores only the barcode value.

Recipes

Retail shelf — EAN-13 with checksum, scan-only

BarcodeScannerField::make('barcode')
    ->formats([BarcodeFormat::Ean13])
    ->validateChecksum()
    ->allowManualInput(false)
    ->required();

Inventory loop — continuous + beep

BarcodeScannerField::make('scan_buffer')
    ->continuous()
    ->beepOnScan()
    ->scanDelay(400)
    ->formats([BarcodeFormat::Code128, BarcodeFormat::Code39]);

Auto-submit lookup form

BarcodeScannerField::make('lookup_code')
    ->autoSubmit()
    ->live()
    ->afterStateUpdated(fn (?string $state) => $this->lookupProduct($state));

Laptop with multiple cameras + slower decode

BarcodeScannerField::make('asset_tag')
    ->allowCameraSwitch()
    ->decodeFps(5) // ~200 ms between attempts
    ->pauseWhenHidden();

Persist symbology from camera

BarcodeScannerField::make('scan')
    ->storeDetectedFormat()
    ->formats([BarcodeFormat::Ean13, BarcodeFormat::Qr]);

// State: ['value' => '5901234123457', 'format' => 'ean_13']
// Input still shows value only; use $get('scan.format') or state array in callbacks.

Custom validation + uniqueness

BarcodeScannerField::make('sku')
    ->formats([BarcodeFormat::Code128])
    ->barcodeRule('regex:/^[A-Z0-9-]{6,32}$/')
    ->unique('products', 'sku')
    ->validationMessages([
        'unique' => 'This SKU is already registered.',
    ]);

Events

Alpine dispatches browser events on successful scans:

Event	Detail
`barcode-scanned`	`{ value, format, engine, statePath }` — `format` / `engine` from camera when available
`barcode-auto-submit`	`{ value, statePath }` — when `autoSubmit()` is enabled

Listen in a parent Alpine scope or Livewire hook as needed.

Validation

Built-in rules run through BarcodeValidator:

Check	Message key
Empty required field	Laravel `validation.required`
Value does not match any allowed format	`barcode_scanner.validation.unrecognized`
EAN/UPC checksum failure	`barcode_scanner.validation.checksum`
Custom `barcodeRule()`	your message

Client-side validation mirrors server rules before accepting a camera scan (invalid scans show an inline error in the modal without closing it).

Accessibility

Scan button: keyboard operable, aria-haspopup="dialog".
Modal: native Filament <x-filament::modal> — focus trap, Escape to close, header close button.
Loading state: aria-live="polite" while camera starts.
Errors: role="alert" in modal body.
@media (prefers-reduced-motion: reduce) disables scan-line animation and spinner.

CSS classes

Class	Purpose
`fff-barcode-scanner`	Root wrapper
`fff-barcode-scanner-field`	Field wrapper (via `getWrapperClasses`)
`fff-barcode-scanner__scan-btn`	Scan trigger in input suffix
`fff-barcode-scanner__viewport`	Camera preview shell (portal-synced on mobile)
`fff-barcode-scanner__reticle`	Scan frame + animated scan line
`fff-barcode-scanner__engine-badge`	Native / ZXing engine indicator (compact, top-left)
`fff-barcode-scanner__toolbar`	Row below preview — switch camera & torch
`fff-barcode-scanner__switch-camera-btn`	Switch camera control
`fff-barcode-scanner__torch-btn`	Torch toggle control
`fff-barcode-scanner-modal`	Filament modal root modifier

Stylesheet: barcode-scanner-field (lazy). Depends on flex-text-input.

Assets

Asset	Loading
CSS `barcode-scanner-field`	Lazy per field
Alpine `barcode-scanner-field`	Lazy per field
ZXing chunk	Dynamic import when camera opens
MP3 `barcode-scan-success.mp3`	Published to `public/.../audio/...`

Rebuild after JS/CSS changes:

cd packages/filament-flex-fields
npm install
npm run build

Playground

Slug: barcode-scanner-field

Demo field	Shows
`barcode__default`	Default + prefilled valid EAN-13
`barcode__ean_only`	EAN/UPC whitelist + checksum
`barcode__continuous`	Continuous inventory mode + beep
`barcode__checksum`	EAN-13 only + checksum enforcement
`barcode__manual_only`	Scan-only (manual input disabled)

Testing

php artisan test --compact packages/filament-flex-fields/tests/Unit/BarcodeScannerFieldTest.php
php artisan test --compact packages/filament-flex-fields/tests/Feature/BarcodeScannerFieldRenderTest.php
node --test packages/filament-flex-fields/tests/js/barcode-scanner-field.test.mjs

Use playground values 5901234123457 (valid EAN-13) and 5901234123450 (invalid checksum) to verify validation.

Component	When to use instead
FlexTextInput	Manual barcode entry without camera
FlexFileUpload	Upload product photos or documents
FlexVerificationCode	Short numeric codes, not product barcodes

​Summary

​Basic usage

​State format

​Supported formats

​Limit formats to specific symbologies

​EAN / UPC only (retail)

​QR only

​Warehouse — Code 128 + ITF

​Dynamic whitelist (Closure)

​Format detection

​Scan UX

​Mobile / iOS notes

​Configuration API

​placeholder(string|Closure|null $placeholder)

​readOnly(bool|Closure $condition = true) / disabled(bool|Closure $condition = true)

​focusOutline(bool|Closure $condition = true)

​Public helper methods

​Model & persistence

​Recipes

​Retail shelf — EAN-13 with checksum, scan-only

​Inventory loop — continuous + beep

​Auto-submit lookup form

​Laptop with multiple cameras + slower decode

​Persist symbology from camera

​Custom validation + uniqueness

​Events

​Validation

​Accessibility

​CSS classes

​Assets

​Playground

​Testing

​Related components