Laravel Client Validation Laravel Package

Getting Started

Install and bootstrap (Laravel path, ~10 minutes):

composer require mrpunyapal/laravel-client-validation
php artisan client-validation:install

Then publish config only if you need to tune behavior:

php artisan vendor:publish --tag=client-validation-config

Render the asset bundle once, in your main layout, before any directive is used:

<head>
    @clientValidationAssets
</head>

Where to look first, in order:

1. config/client-validation.php — validation_mode (blur | input | submit), debounce_ms (default 300), enable_ajax_validation. This is the file you'll actually touch when UX feels wrong.
2. docs/md/validation-rules.md — the canonical rule list (104 client-side + 5 remote). Bookmark it; you will consult it far more than the README.
3. The package's Boost skill (laravel-client-validation-development) if your app runs Laravel Boost — php artisan boost:update --discover makes AI-assisted edits follow the package's recommended Blade/Alpine/Livewire/Filament patterns instead of inventing them.

First use case — a single field, zero JavaScript. This is the highest-leverage entry point because it proves the pipeline end-to-end without touching Alpine state:

<input name="email" x-validate="'required|email'">

Or fully framework-free, using the Blade attribute directives plus the data-attribute runner:

<form data-validate>
    <input name="email" @rules('email', 'required|email', ['mode' => 'blur'])>
    <input name="username" @validateLive('username', 'required|alpha_dash|min:3')>
    <input name="password" @validateBlur('password', 'required|min:8')>
    <button type="submit">Submit</button>
</form>

If that field shows an error on blur without you writing a listener, the assets are mounted correctly and everything else is a variation on this.

Standalone path (no Composer): npm install laravel-client-validation and import subpaths (/core, /alpine, /vanilla, /livewire, /react, /vue). Only use this if the validation lives in a JS-first codebase or a non-Laravel backend; otherwise the Composer path keeps rules co-located with FormRequests, which is the whole point.

Implementation Patterns

Pattern 1: FormRequest as the single source of truth (the one you should standardize on)

This is the package's real value proposition: stop maintaining a second, drifting rule set in JavaScript.

public function create()
{
    $validation = ClientValidation::fromRequest(CreateUserRequest::class);
    return view('users.create', compact('validation'));
}

<div x-data="validation(@js($validation))">
    <input x-model="form.email" @blur="validate('email')" name="email">
    <span x-text="error('email')" x-show="hasError('email')"></span>
</div>

Day-to-day rule: if a rule can be expressed in the FormRequest, it goes there — never duplicated in Blade and never duplicated in $rules on the Livewire component and the controller. Extract an abstract base request or a trait if several forms share fragments.

Pattern 2: The validation() Alpine component for multi-field forms

<div x-data="validation({
    rules: {
        email: 'required|email',
        password: 'required|min:8',
        password_confirmation: 'required|same:password'
    },
    messages: {
        'email.required': 'Please enter your email',
        'password.min': 'Password is too short'
    }
})">
    <form @submit.prevent="submit(async (data) => {
        await fetch('/users', { method: 'POST', body: JSON.stringify(data) });
    })">
        <button :disabled="validating || !isValid()">Submit</button>
    </form>
</div>

Working mental model of the API surface:

Note that isValid() and hasErrors() are current-state reads, not “run validation now” — on first paint neither has run, so isValid() is optimistic. Gate the submit button on validating || !isValid() and let submit() be the authoritative check.

Pattern 3: Directive modifiers as the validation-timing policy

Choose per field based on cost, not preference:

• x-validate — blur (default). Use for almost everything.
• x-validate.live — validate on input, debounced by config. Reserve for fields where incremental feedback matters (username availability) and accept the extra noise.
• x-validate.submit — only on submit. Use for fields where mid-typing errors are hostile (passwords, confirmation fields, optional freeform text).

For remote rules, .live plus a local rule first is the safe combination:

<input name="email" x-validate.live="'bail|required|email|unique:users,email'">

bail means the AJAX call for unique is skipped entirely while the field is empty or syntactically invalid — you will otherwise fire a request per keystroke against the database.

Pattern 4: Livewire — declare rules in PHP, validate in the browser

Component side, reuse the rules you already wrote:

use Livewire\Component;
use MrPunyapal\ClientValidation\Livewire\WithClientValidation;

class CreateUser extends Component
{
    use WithClientValidation;

    public string $email = '';
    // ...
    protected $rules = ['email' => 'required|email'];
}

View side:

<div x-data="{ clientRules: @json($this->getClientRules()) }">
    <input wire:model.live="email" x-wire-validate="clientRules.email" name="email">
    <span class="validation-error" data-error="email"></span>
</div>

Two practical notes: use wire:model.live (not deferred) when you want the browser-side check and the server-side property to stay in sync, and use the client-validation-error / client-validation-cleared events to bridge into PHP when you need to log or drive server-side UI state.

Pattern 5: Filament for admin panels

$panel->plugins([
    ClientValidationPlugin::make()
        ->enableRemoteValidation()
        ->validationMode('live'),
]);

For custom fields, apply HasClientValidation once as a trait and let all inheritors opt in via ->clientValidation('required|email'). For one-offs use the prebuilt ClientValidatedField. Keep validationMode('live') off by default if the panel has heavy remote rules — live mode plus a large table means a request per keystroke per field.

Pattern 6: Custom rules — decide the tier before you write it

• Browser-only (format rules, cross-field checks): RuleRegistry.extend() / LaravelClientValidation.extend(). Instant, no round-trip.
• Needs database or auth state (unique, current_password-style): ClientValidation::extend() on the PHP side so Laravel treats it as server-side.

Rule functions must keep the documented signature and return false rather than throwing:

export default function ruleName(value, params, field, context = {}) {
    return /* boolean */;
}

Pattern 7: Debugging with the event hooks

Wire these once in a scratch environment and you can trace almost any issue:

field:validating → field:validated → form:validating → form:validated.

Attach a console.log on field:validated and you immediately see whether a failure is a bad rule string, a missing sibling value, or a remote rejection — three very different bugs that all surface as “the field is red.”

Gotchas and Tips

Client validation is UX, never security. Every browser rule must still exist server-side in the FormRequest or $request->validate(). Treat the client layer as a latency optimization; if you ever delete the server rule because “the browser catches it,” you've shipped a vulnerability.

Livewire and Filament now live in separate Composer packages. The core package's docs reference MrPunyapal\ClientValidation\Livewire\WithClientValidation and ...\Filament\ClientValidationPlugin, but the repo notes those integrations were split into mrpunyapal/client-validation-livewire and mrpunyapal/client-validation-filament. If the trait or plugin class is “not found” after installing only the core package, that's why — check composer show before debugging your own code. The Livewire snapshot hook auto-registers from the core provider once the subpackage is present.

@clientValidationAssets exactly once. Duplicating it (e.g. layout and a Livewire layout) registers Alpine plugins twice, and you get “Alpine: Cannot reference the same directive twice” or silently doubled remote requests. Grep your layouts before adding it to a second one.

fromRequest() only translates what it can translate. Closure rules, Rule::when(...), and custom Rule objects have no browser equivalent and will be dropped or passed through opaquely. Inspect the emitted JSON (@js($validation)) in the page source the first time you wire a complex FormRequest — that's the fastest way to spot a rule that quietly didn't make it.

Cross-field rules need the sibling field declared. same:password, confirmed, required_if:role,admin, and gt:start_date all read other values from the same rule set. If password_confirmation isn't in the rules map (even as just 'nullable'), it won't be in the payload and the comparison silently misbehaves.

File rules behave differently from string rules. image, mimes, mimetypes, and dimensions expect an actual File object from an <input type="file">. Testing them by calling validateAll({ avatar: 'photo.jpg' }) always fails, and that failure looks like a broken rules engine rather than a type mismatch.

Remote rules are the whole cost center. unique, exists, password, current_password, encoding each hit your app over AJAX. Mitigations, in order of impact: put a cheap local rule first, use bail, keep debounce_ms at 300+ (raise it to 500 for unique on large tables), and confirm enable_ajax_validation is only true where you actually need it. Also check the AJAX route sits behind the right middleware — on multi-guard apps current_password and unique can behave surprisingly when the guest/auth context differs from the form's.

Batch when validating whole forms. Multiple field-by-field remote calls on submit produce a request waterfall. The package supports batch validation specifically for this; use it in submit() flows rather than looping validate() over every field.

After publishing config, remember config:cache. The validation_mode and debounce_ms values are read from cached config in production, so an edit that “does nothing” is almost always a stale cache.

Pin the version. Eleven stars, zero dependents, and a rapid release cadence mean the public surface is still settling — the Livewire/Filament split is proof. Commit a specific version constraint, read CHANGELOG.md before minor bumps, and read the diff of resources/js/dist/ if behavior changes unexpectedly. MIT license means you can fork or vendor the built bundle if a release breaks you.

Don't hand-edit generated artifacts. If you're working inside the package (or a fork), resources/js/dist/ and everything under docs/ except docs/md/ are build output. Change packages/js/*/src/, src/, or docs/md/*.md and rebuild (npm run build, composer docs:build).

Bundle size is a real lever. If you're consuming the npm package rather than the Blade bundle, import subpaths (laravel-client-validation/core, /alpine) instead of the meta-package — importing the root entry pulls every adapter. For a Laravel-only app the published IIFE bundle is simplest; for a Vite + Vue/React app, subpath imports are the correct call.

Test remote flows in a real app. The repo uses a gitignored /workground/ Laravel app for this. Do the same: a package's unit tests won't catch a CSRF mismatch, a route middleware guard, or a Livewire v3-vs-v4 sync difference. One throwaway Laravel app with three forms (Alpine, Livewire, Filament) will surface more than any test suite you write in isolation.