<x-widget.select>
Select Blade component for Laravel and Livewire
A styled select with keyboard support, type-to-jump and optional search. Single or multiple, and clearable. Options can carry meta (a balance, a count) shown beside them. With search-url it searches your app as you type, for lists too long to send to the page. Works with Livewire wire:model, including options that change between renders.
php artisan bladewell:add select
- Also adds
- Icon, Search
- Used by
- Filter builder, Table
- Works with
- Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+
- Guides
- Build a Laravel form from your validation rules · Laravel data table with sorting, filters, pagination · Using Blade components in Livewire 3 and 4 · Livewire multi-step form with validation per step · Laravel searchable select that loads from the database · Add charts and a rich text editor to a Laravel app
Usage
Search endpoint
The URL in search-url answers GET ?q=… with JSON: a list, or a resource collection ({"data": [...]}). Each option is a string, or value and label, with optional meta and disabled. Pass the chosen record(s) in options so the field shows them. It answers whoever calls it, not only this field, and the meta here is an email: so only signed in, and only the customers this person may see.
Route::get('/customers/search', function (Request $request) {
$q = $request->validate(['q' => ['required', 'string', 'max:100']])['q'];
// Their own (or their team's), never Customer::query(), which would list everyone's.
return $request->user()->customers()
// % and _ typed match themselves, the same on every database (ESCAPE '!'), and LOWER() ignores case.
->whereRaw("LOWER(name) LIKE LOWER(?) ESCAPE '!'", ['%'.str_replace(['!', '%', '_'], ['!!', '!%', '!_'], $q).'%'])
->orderBy('name')
->limit(20)
->get()
->map(fn (Customer $customer): array => ['value' => $customer->id, 'label' => $customer->name, 'meta' => $customer->email]);
})->middleware(['auth', 'throttle:120,1'])->name('customers.search');
// On submit, check the chosen id through that same relationship, in the Form Request's rules(). Not a plain
// exists:customers,id: that takes any customer's id sent straight to the form, though the search never offered it.
'customer_id' => ['required', 'integer', fn (string $attribute, mixed $value, Closure $fail) => $this->user()->customers()->whereKey($value)->exists() || $fail('Choose one of your customers.')],
Livewire
In a Livewire component, bind with wire:model (deferred) or wire:model.live, single or multiple. Without :value the select shows the bound property, so it keeps the choice through every render, and setting or clearing the property in PHP updates it. Options may change between renders: here the cities follow the country (reset $city in updatedCountry()).
<div>
<x-widget.select name="country" label="Country" :options="$countries" wire:model.live="country" />
<x-widget.select name="city" label="City" placeholder="Pick a city" :options="$cities" wire:model.live="city" searchable :search-min="8" />
<x-widget.select name="tags" label="Tags" multiple display="chips" clearable :options="$tags" wire:model="selectedTags" />
<button type="button" wire:click="save">Save</button>
</div>
On the server
The select can't stop a request that skips it. Here's what to check on your server, and what to keep cheap.
Security
-
The options in the page don't limit what can be posted. Check the value with
Rule::in(), or for records through the same scope the options came from (the person's own customers), not a plainexists:, which takes anyone's id. Withmultiple, cap how many withmax:on the array. -
With
search-url, the endpoint lists records to whoever calls it, not only through this field. Scope it to what the person may see, and send only the value, label and meta.OWASP: Insecure direct object references · Laravel: Authorization
Server cost
-
With
search-url, it asks as people type. Considerlimit()(20 is plenty), throttle the route, raisesearch-min-lengthto 2 or 3 on big tables, and index the column you search.like '%…%'can't use a normal index, so a prefix match or full-text search scales better.
Examples
Select
Options can be a plain list, a key => label map, or rows with id, name and extra meta, which shows beside each option in the list and beside the choice. Long lists get a search box with searchable.
Show code Hide code
<div class="grid gap-6 sm:grid-cols-2">
<x-widget.select name="network" label="Network" placeholder="Choose a network" value="trc20" :options="[
['id' => 'trc20', 'name' => 'TRC20 (Tron)', 'formattedBalance' => '1,250.00 USDT'],
['id' => 'erc20', 'name' => 'ERC20 (Ethereum)', 'formattedBalance' => '310.45 USDT'],
['id' => 'bep20', 'name' => 'BEP20 (BNB Chain)', 'formattedBalance' => '0.00 USDT', 'disabled' => true],
]" />
<x-widget.select name="country" label="Country" placeholder="Select a country" searchable search-placeholder="Search countries" :options="[
'MY' => 'Malaysia', 'SG' => 'Singapore', 'ID' => 'Indonesia', 'TH' => 'Thailand', 'VN' => 'Vietnam',
'PH' => 'Philippines', 'IN' => 'India', 'JP' => 'Japan', 'KR' => 'South Korea', 'AU' => 'Australia',
'NZ' => 'New Zealand', 'GB' => 'United Kingdom', 'US' => 'United States', 'AE' => 'United Arab Emirates',
]" />
</div>
Multi select
multiple submits networks[] and keeps the list open while you pick. display sets how the choices show: chips (each removable; Backspace removes the last), count ("3 selected", full list in the tooltip) or list (joined, the default). clearable adds a button to empty it. Listen for the select:change event to react in JS.
Show code Hide code
@php
$networks = [
'trc20' => 'TRC20 (Tron)',
'erc20' => 'ERC20 (Ethereum)',
'bep20' => 'BEP20 (BNB Chain)',
'sol' => 'Solana',
'arb' => 'Arbitrum',
];
@endphp
<div class="grid gap-6 sm:grid-cols-2">
<x-widget.select name="networks" label="Networks" placeholder="Choose networks" multiple clearable display="chips" :value="['trc20', 'erc20', 'bep20']" :options="$networks" class="sm:col-span-2" />
<x-widget.select name="alert_networks" label="Alert me on" placeholder="Any network" multiple display="count" count-label=":count networks" :value="['trc20', 'sol', 'arb']" :options="$networks" />
<x-widget.select name="payout_networks" label="Payout networks" placeholder="Choose networks" multiple :value="['trc20', 'bep20']" :options="$networks" />
</div>
Search your app
For lists too long to send to the page (customers, products; past about 100 options, each about 0.8 KB of HTML), search-url asks your app as you type and shows what it answers. Pass the chosen one in options, so the field shows it before any search. Try "an", or part of an email.
Show code Hide code
<x-widget.select name="customer_id" label="Customer" placeholder="Choose a customer" class="max-w-md"
search-url="{{ route('customers.search') }}"
value="7"
:options="[['value' => 7, 'label' => 'Ana Silva', 'meta' => '[email protected]']]" />
Search your app for several
With multiple, choices stay picked while you search for more. Options you pass that aren't chosen show until you type: here, a few people to start from.
Show code Hide code
<x-widget.select name="assignees" label="Assign to" placeholder="Search people" multiple display="chips" class="max-w-md"
search-url="{{ route('customers.search') }}"
:value="[9]"
:options="[
['value' => 9, 'label' => 'Ben Carter', 'meta' => '[email protected]'],
['value' => 27, 'label' => 'Priya Sharma', 'meta' => '[email protected]'],
['value' => 11, 'label' => 'Chloé Martin', 'meta' => '[email protected]'],
]" />
Props
Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.
<x-widget.select>
| Prop | Default | Description |
|---|---|---|
| name |
null
|
What the value submits as; with multiple, name[] (a trailing [] is added for you). |
| id |
null
|
Defaults to one made from the name. |
| label |
null
|
Shown above the field (or inside it, with inner-label), and its name for screen readers. |
| options |
[]
|
A list (['Red', 'Blue']), a value => label map, or rows: ['value' => 1, 'label' => 'Savings', 'meta' => '$120', 'disabled' => true]; id and name work as value and label. meta shows at the end of the option's line, e.g. a count. Every option is about 0.8 KB of HTML on the page: past about 100, use search-url and send only the chosen one(s). |
| value |
null
|
The chosen value (an array with multiple). Old input wins after a failed submit. With wire:model and no value, it comes from the bound Livewire property. |
| placeholder |
''
|
Shown while nothing is chosen. |
| error |
null
|
An error message of your own; otherwise the validation error for the name, from the session. |
| 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 opened or changed (its value still submits). |
| readonly |
false
|
Shown, and submitted, but it can't be changed: the list doesn't open. With disabled, disabled wins. |
| searchable |
false
|
A search box at the top of the list, once there are at least search-min options. |
| search-min |
12
|
How many options it takes before searchable shows the search box. |
| search-placeholder |
'Search'
|
The search box's placeholder. |
| no-results |
'No results'
|
Shown when the search matches nothing. |
| search-url |
null
|
Searches your app instead of the options on the page, for lists too long to send: a URL that answers GET ?q=… with JSON, a list or {"data": [...]}, each option a string or ['value' => 7, 'label' => 'Ana Silva', 'meta' => …]. Pass the chosen option(s) in options, so the field shows them before any search; any others there show until you type. |
| search-min-length |
2
|
With search-url: how many characters to type before asking. |
| searching |
'Searching…'
|
With search-url: shown, and announced, while a search runs. |
| search-failed |
'Couldn\'t search. Try again.'
|
With search-url: shown, and announced, when a search fails. |
| inner-label |
false
|
The label inside the field, above the value, instead of above the field. |
| multiple |
false
|
Choose several: the list stays open and each pick toggles an option. |
| clearable |
false
|
An × button that clears the choice. |
| display |
'list'
|
With multiple, how the choices show: list (labels joined), chips (removable) or count ("3 selected"). |
| count-label |
':count selected'
|
display="count": the text, with :count for the number. |
| required-message |
'Choose an option.'
|
With required: the message when nothing is chosen. |
Accessibility
All 4 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 select 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/select/index.blade.php Show
resources/js/widget/select/index.js Show
app/View/Widget/ElementIds.php Show
app/View/Widget/FormField.php Show