<x-widget.captcha>
Captcha Blade component for Laravel and Livewire
An image captcha, inline or stacked large above the answer, with an audio version (give one with every image, or people who can't see it can't get through) and a refresh button. Or Cloudflare Turnstile, reCAPTCHA or hCaptcha, checked on the server with the Captcha rule. In Livewire the image (or the provider's widget) stays put through every render, so the code being answered never changes under you.
php artisan bladewell:add captcha
- Also adds
- Icon
- Works with
- Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+
- Guide
- Using Blade components in Livewire 3 and 4
Usage
Captcha validation
An image captcha is checked by whatever generated it, e.g. mews/captcha's rule.
'captcha' => ['required', 'captcha'],
// A provider token is checked with the provider. Keys go in config/services.php, read from .env:
// 'turnstile' => ['key' => env('TURNSTILE_SITE_KEY'), 'secret' => env('TURNSTILE_SECRET_KEY')],
use App\Rules\Captcha;
'cf-turnstile-response' => ['required', new Captcha('turnstile')],
// reCAPTCHA: 'g-recaptcha-response', hCaptcha: 'h-captcha-response' (or Captcha::field('hcaptcha')).
Livewire
An image captcha in a Livewire component ($captchaUrl from the component, for example captcha_src() with mews/captcha): bind the answer with wire:model; no name is needed, and its error is read under the property. The image (and the audio) stay put through every render, so the code being answered never changes under you; the refresh button still loads a new one. Validate it as usual in the component: 'captcha' => ['required', 'captcha']. Turnstile, reCAPTCHA and hCaptcha bind the same way: wire:model gets the provider's token when it's issued, and an empty one when it expires; check it with 'token' => ['required', new Captcha('turnstile')]. Send the form with wire:submit: a token is good for one check, so once a submit has sent it the provider gives a new one, after the render that comes back.
<form wire:submit="send" class="space-y-5">
<x-widget.captcha label="Type the characters" :src="$captchaUrl" wire:model="captcha" />
{{-- Or, with a provider instead of the image: --}}
<x-widget.captcha provider="turnstile" label="Security check" wire:model="token" />
<button type="submit">Send</button>
</form>
On the server
The captcha can't stop a request that skips it. Here's what to check on your server, and what to keep cheap.
Security
-
Check the answer on the server on every submit (the
Captcharule), and keep provider secrets in.env. A captcha slows bots; it doesn't replace rate limiting or authorization.
Server cost
-
Each provider check is a call to another server, and some bill past a free tier. Consider it only where abuse happens (sign-up, contact, password reset), or only after a few failed tries.
Examples
Captcha
$captchaUrl is your captcha image's URL from the controller (for example captcha_src() with mews/captcha), and $captchaAudioUrl the same code spoken, so people who can't see the image can still get through. The refresh button shows another code.
Pass
$captchaUrl and
$captchaAudioUrl
from your controller.
Show code Hide code
<x-widget.captcha label="Captcha" placeholder="Enter the text" :src="$captchaUrl" :audio-src="$captchaAudioUrl" class="max-w-sm" />
Captcha stacked
layout="stacked" shows a large, readable image above the answer. audio-src adds a button that plays the code aloud, so people who can't see the image can still pass; refresh reloads both. If the image fails to load, a message asks for another.
Pass
$captchaUrl and
$captchaAudioUrl
from your controller.
Show code Hide code
<x-widget.captcha label="Type the characters you see or hear" layout="stacked" :src="$captchaUrl" :audio-src="$captchaAudioUrl" class="max-w-sm" />
Captcha provider
provider uses Cloudflare Turnstile, Google reCAPTCHA or hCaptcha instead of an image: most people just tick a box, or see nothing. The site key comes from config/services.php; check the token on the server with the Captcha rule (see Usage).
Show code Hide code
<x-widget.captcha provider="turnstile" label="Security check" />
Props
Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.
<x-widget.captcha>
| Prop | Default | Description |
|---|---|---|
| name |
'captcha'
|
What the answer submits as. With a provider, the provider's own token field is used, and wire:model binds the token. |
| id |
null
|
Defaults to one made from the name (or the wire:model property). |
| src |
null
|
The image URL (e.g. route('captcha')); refreshing fetches it again, for a new code. |
| audio-src |
null
|
The URL of a spoken version: adds a play button. Give one with every image: without it, someone who can't see the image has no way through the form (WCAG 1.1.1). |
| layout |
'inline'
|
inline (the image beside the field) or stacked (large, above it). |
| provider |
null
|
turnstile, recaptcha or hcaptcha instead of an image; check it with new Captcha($provider). |
| site-key |
null
|
The provider's public site key; defaults to config('services.{provider}.key'). |
| theme |
'auto'
|
The provider widget's theme: auto, light or dark. |
| size |
'normal'
|
The provider widget's size: normal or compact. |
| label |
null
|
Shown above the field, and its name for screen readers. |
| placeholder |
null
|
Shown while it's empty. |
| error |
null
|
An error message of your own; otherwise the validation error for the name, from the session or Livewire. |
| info |
null
|
A hint under the field. |
| bag |
'default'
|
Which error bag to read the error from. |
| disabled |
false
|
Greyed out: it can't be changed. |
Accessibility
All 3 examples above are checked with axe-core against the WCAG 2.2 A and AA rules, in the light theme and the dark one, both as the page draws and with each popover, dialog, toast and tooltip opened, on every change. A change that fails can't be merged. Where axe can't decide, such as contrast on SVG text, the test measures the colours itself instead of letting it pass.
Automated checks can't judge everything: how it sounds in a screen reader, and how it feels to use from the keyboard, still need a person. Check those on your own pages too.
Source
What bladewell:add captcha writes to your app with the default namespaces. Prefer to copy by hand? Take these files, plus the ones from
the components it also adds and Field, and the theme and base CSS.
resources/views/components/widget/captcha/index.blade.php Show
resources/js/widget/captcha/index.js Show
app/View/Widget/ElementIds.php Show
app/View/Widget/FormField.php Show
app/Rules/Captcha.php Show