Skip to content
Bladewell

<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.

PHP
'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.

Blade
<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 Captcha rule), and keep provider secrets in .env. A captcha slows bots; it doesn't replace rate limiting or authorization.

    Laravel: Rate limiting

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.

    Laravel: Rate limiting

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.

Captcha: type the characters shown
Show code
Blade
<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.

Captcha: type the characters shown
Show code
Blade
<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).

Security check
Show code
Blade
<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
index.blade.php
resources/js/widget/captcha/index.js Show
index.js
app/View/Widget/ElementIds.php Show
ElementIds.php
app/View/Widget/FormField.php Show
FormField.php
app/Rules/Captcha.php Show
Captcha.php