Filament QR Code Scanner (html5-qrcode)

A Filament form action for scanning barcodes and QR codes using the device camera. Built with the html5-qrcode library.

Features

• Three-tier architecture: Use as Filament action, standalone Livewire component, or pure Alpine.js
• Scan QR codes and various barcode formats (Code128, Code39, EAN-13, UPC-A, ITF, and more)
• Works on mobile and desktop devices with camera access
• Configurable scanner options: fps, qrbox, aspect ratio, camera facing mode
• Automatic camera switching (front/back) or force specific camera
• Transform scanned values with PHP closures or JavaScript functions
• Header action support for standalone scanning (e.g., attendance check-in)
• Fully customizable labels and error messages
• Dark mode support
• Accessible with ARIA labels

Requirements

• PHP 8.2+
• Laravel 11.28+
• Filament 4.x or 5.x
• Livewire 3.x or 4.x

Installation

Install the package via Composer:

composer require chengkangzai/filament-qrcode-scanner-html5

The package will auto-register its service provider.

Upgrading from v1.x

v2.0 requires Filament 4, PHP 8.2+, and Laravel 11.28+.

For Filament 3 support, use v1.x:

composer require chengkangzai/filament-qrcode-scanner-html5 "^1.3"

See UPGRADE.md for detailed migration instructions.

Usage

Basic Usage

Add the BarcodeScannerAction as a suffix action to any text input:

use CCK\FilamentQrcodeScannerHtml5\BarcodeScannerAction;

TextInput::make('barcode')
    ->suffixAction(BarcodeScannerAction::make())

Limit Supported Formats

Restrict scanning to specific barcode formats:

use CCK\FilamentQrcodeScannerHtml5\BarcodeScannerAction;
use CCK\FilamentQrcodeScannerHtml5\Enums\BarcodeFormat;

TextInput::make('product_code')
    ->suffixAction(
        BarcodeScannerAction::make()
            ->supportedFormats([
                BarcodeFormat::QRCode,
                BarcodeFormat::Code128,
                BarcodeFormat::Ean13,
            ])
    )

Transform Scanned Values (PHP)

Use a PHP closure to transform the scanned value server-side:

use CCK\FilamentQrcodeScannerHtml5\BarcodeScannerAction;
use CCK\FilamentQrcodeScannerHtml5\Enums\BarcodeFormat;

TextInput::make('barcode')
    ->suffixAction(
        BarcodeScannerAction::make()
            ->modifyStateUsing(fn (string $value, ?BarcodeFormat $format) =>
                // Strip leading zeros from ITF barcodes
                $format === BarcodeFormat::ITF
                    ? ltrim($value, '0')
                    : $value
            )
    )

Transform Scanned Values (JavaScript)

Use a JavaScript function to transform the scanned value client-side:

use CCK\FilamentQrcodeScannerHtml5\BarcodeScannerAction;

TextInput::make('barcode')
    ->suffixAction(
        BarcodeScannerAction::make()
            ->modifyStateUsingJs("(value, formatId) => value.replace(/^0+/, '')")
    )

Format IDs for JavaScript: QR=0, PDF417=10, Code39=4, Code128=6, DataMatrix=12, ITF=8

Customize Labels and Messages

use CCK\FilamentQrcodeScannerHtml5\BarcodeScannerAction;

TextInput::make('barcode')
    ->suffixAction(
        BarcodeScannerAction::make()
            ->switchCameraLabel('Toggle Camera')
            ->cameraUnavailableMessage('No camera detected on this device.')
            ->permissionDeniedMessage('Please allow camera access in your browser settings.')
    )

Header Action (Standalone Scanning)

Use BarcodeScannerHeaderAction for standalone scanning without a form field, such as attendance check-in or inventory lookup:

use CCK\FilamentQrcodeScannerHtml5\BarcodeScannerHeaderAction;
use CCK\FilamentQrcodeScannerHtml5\Enums\BarcodeFormat;
use Filament\Notifications\Notification;

// In your Filament Resource page (ListRecords, ViewRecord, etc.)
protected function getHeaderActions(): array
{
    return [
        BarcodeScannerHeaderAction::make()
            ->label('Scan Attendance')
            ->afterScan(function (string $value, ?BarcodeFormat $format) {
                $user = User::where('qr_code', $value)->first();

                if (! $user) {
                    Notification::make()
                        ->title('User not found')
                        ->danger()
                        ->send();

                    return null; // Just close the modal
                }

                // Mark attendance
                $user->attendances()->create(['checked_in_at' => now()]);

                // Redirect to user page
                return redirect()->route('filament.admin.resources.users.view', $user);
            }),
    ];
}

The afterScan callback can return:

• redirect('/url') or redirect()->route('name', $params) - Redirect to a URL
• '/url' - String URL to redirect
• null - Just close the modal (useful after showing a notification)

Scanner Configuration Options

Configure scanner behavior with these options (available on all actions):

use CCK\FilamentQrcodeScannerHtml5\BarcodeScannerAction;
use CCK\FilamentQrcodeScannerHtml5\Enums\BarcodeFormat;

TextInput::make('barcode')
    ->suffixAction(
        BarcodeScannerAction::make()
            ->fps(15)                          // Frames per second (1-30, default: 10)
            ->qrbox(250)                       // Square focus box (250x250)
            ->qrbox(300, 200)                  // Rectangle focus box (300x200)
            ->aspectRatio(1.777778)            // Camera aspect ratio (16:9)
            ->preferBackCamera()               // Force back/environment camera
            ->preferFrontCamera()              // Force front/user camera
            ->facingMode('environment')        // Alternative: 'user' or 'environment'
            ->supportedFormats([...])          // Limit barcode formats
            ->iconOnly()                       // Show only icon (no text label)
            ->controlPosition('center')        // Align controls: 'left', 'center', 'right'
            ->hideCameraName()                 // Hide camera name label
    )

Configuration Options Reference

Standalone Usage (Without Filament)

This package can be used outside of Filament panels for custom integrations.

Livewire Component

Use the standalone Livewire component in any Laravel application:

// In your Livewire component
use CCK\FilamentQrcodeScannerHtml5\Enums\BarcodeFormat;

class CheckInPage extends Component
{
    public $scannedValue = null;

    public function handleScan($value, $formatId)
    {
        $this->scannedValue = $value;
        $format = BarcodeFormat::fromHtml5QrcodeFormat($formatId);

        // Your custom logic here
        $this->processCheckIn($value);
    }

    public function render()
    {
        return view('livewire.check-in-page');
    }
}

{{-- In your blade view --}}
<div>
    <livewire:barcode-scanner
        wire:key="scanner"
        @barcode-scanned.window="$wire.handleScan($event.detail.value, $event.detail.formatId)"
    />

    @if($scannedValue)
        <p>Scanned: {{ $scannedValue }}</p>
    @endif
</div>

Pure Alpine.js Component

Use the base component without any framework dependencies:

<x-filament-qrcode-scanner-html5::barcode-scanner
    id="my-scanner"
    :config="[
        'fps' => 15,
        'qrbox' => ['width' => 250, 'height' => 250],
        'aspectRatio' => 1.777778,
        'facingMode' => 'environment'
    ]"
    :supported-formats="[0, 6, 8]"  {{-- QR Code, Code128, ITF --}}
    :labels="[
        'switchCamera' => 'Toggle Camera',
        'cameraUnavailable' => 'No camera found',
        'permissionDenied' => 'Camera access denied'
    ]"
    @barcode-scanned.window="handleScan($event.detail)"
    @barcode-scanner-error.window="handleError($event.detail)"
/>

<script>
function handleScan(detail) {
    console.log('Scanned value:', detail.value);
    console.log('Format:', detail.formatName);
    console.log('Format ID:', detail.formatId);
    console.log('Timestamp:', detail.timestamp);
    console.log('Scanner ID:', detail.scannerId);
}

function handleError(detail) {
    console.error('Scanner error:', detail.error);
    console.log('Error type:', detail.errorType);
}
</script>

Browser Events

The Alpine.js component emits these browser events:

Error types: 'not_supported', 'overconstrained', 'permission_denied', 'camera_unavailable', 'unknown'

Supported Barcode Formats

Publishing Views

If you need to customize the scanner modal view:

php artisan vendor:publish --tag=filament-qrcode-scanner-html5-views

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover any security-related issues, please email pycck@hotmail.com instead of using the issue tracker.

Credits

• CCK
• html5-qrcode by Minhaz

License

The MIT License (MIT). Please see License File for more information.