<x-widget.field>
Field Blade component for Laravel and Livewire
Use this to wrap a control of your own so it matches the rest: the same label, box, error and hint, required mark and character counter, and an error that clears the moment the value changes. It's the frame every form control here is built on, so you never need it around those; they already have it. Works in Livewire around a wire:model control.
php artisan bladewell:add field
Already included with every component in Forms. Run this only to wrap a control of your own.
- Also adds
- Icon
- Used by
- Captcha, Checkbox, Colour picker, Date range picker, Date picker, File upload, Filter builder, Image cropper, Number, OTP, Password, Phone, Radio, Repeater, Search, Select, Show if, Slider, Sortable list, Switch, Tags input, Text input, Textarea, Time picker, Tree, Verification code
- Works with
- Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+
- Guide
- Add charts and a rich text editor to a Laravel app
Usage
Livewire
Around your own control in a Livewire component: put wire:model on the control, and pass the frame the property's errors with :error, since it can't see your control's binding. Give the control a fixed id (the one the frame's label points at): Livewire's morph matches elements by id, and a changing one drops focus.
<x-widget.field id="volume" label="Volume" :error="$errors->get('volume')" bare>
<input id="volume" type="range" min="0" max="100" wire:model.live="volume" class="accent-primary h-12 w-full cursor-pointer">
</x-widget.field>
Examples
Custom control
Your own control, matched to the inputs. Text-like markup goes in the box; bare drops the box for a control that draws itself. Give it the id the label points at.
Charged monthly.
Show code Hide code
<div class="grid gap-6 sm:grid-cols-2">
<x-widget.field id="price" label="Price" info="Charged monthly.">
<div class="border-line relative my-3 flex shrink-0 items-center border-e">
<select name="currency" aria-label="Currency" class="text-foreground h-full cursor-pointer appearance-none bg-transparent ps-5 pe-9 outline-none">
<option>USD</option>
<option>EUR</option>
<option>GBP</option>
</select>
<x-widget.icon name="chevron-down" class="text-muted pointer-events-none absolute inset-e-3 size-4" />
</div>
<input id="price" type="text" inputmode="decimal" name="price" value="29.00" aria-describedby="price-info" class="w-full min-w-0 bg-transparent ps-4 pe-5 tabular-nums outline-none">
</x-widget.field>
<x-widget.field id="volume" label="Volume" bare>
<input id="volume" type="range" name="volume" min="0" max="100" value="60" class="accent-primary h-12 w-full cursor-pointer">
</x-widget.field>
</div>
States
An error, as from $errors->get(): one message or several. It clears the moment the value changes.
That handle is taken.
0 / 160
Show code Hide code
<div class="grid gap-6 sm:grid-cols-2">
<x-widget.field id="handle" label="Handle" error="That handle is taken." required>
<input id="handle" name="handle" value="bladewell" required aria-invalid="true" aria-describedby="handle-error" class="w-full bg-transparent px-4 outline-none">
</x-widget.field>
<x-widget.field id="bio" label="Bio" box="items-start" counter="160" count="0">
<textarea id="bio" name="bio" maxlength="160" rows="3" class="w-full resize-none bg-transparent px-4 py-3 outline-none"></textarea>
</x-widget.field>
</div>
Props
Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.
<x-widget.field>
| Prop | Default | Description |
|---|---|---|
| id | Required | The control's id, which the label points at. |
| label |
null
|
Shown above the field, and its name for screen readers. |
| error |
null
|
The error message(s) to show under the box. |
| info |
null
|
A hint under the field. |
| disabled |
false
|
Greyed out: it can't be changed. |
| readonly |
false
|
Shown, and submitted, but it can't be edited. |
| box |
'h-12 items-center'
|
Classes for the field's box (its height and alignment). |
| bare |
false
|
No box, for controls that draw their own (OTP boxes, a provider's captcha). |
| required |
false
|
Marks the label as required. |
| announce-required |
false
|
Also says "required" to screen readers, for a control that can't carry required itself. |
| labels-control |
true
|
The label is a <label for> the control; false for markup that isn't yours, named by the label's id instead. |
| counter |
null
|
A count under the field, against this maximum. |
| count |
0
|
The count to start at. |
Slots
- <x-slot:before>
- Content between the label and the box (the stacked captcha's image).
- <x-slot:after>
- Content under the box but above the messages (the password's checklist).
Accessibility
All 2 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 field 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 the theme and base CSS.
resources/views/components/widget/field/index.blade.php Show
resources/js/widget/field/index.js Show