Skip to content
Bladewell

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

PHP
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()).

Blade
<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 plain exists:, which takes anyone's id. With multiple, cap how many with max: on the array.

    OWASP: Input validation · Laravel: The in rule

  • 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. Consider limit() (20 is plenty), throttle the route, raise search-min-length to 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.

    Laravel: Rate limiting routes · Laravel: Scout

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.

TRC20 (Tron)1,250.00 USDT
ERC20 (Ethereum)310.45 USDT
BEP20 (BNB Chain)0.00 USDT
Malaysia
Singapore
Indonesia
Thailand
Vietnam
Philippines
India
Japan
South Korea
Australia
New Zealand
United Kingdom
United States
United Arab Emirates
Show code
Blade
<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.

TRC20 (Tron) ERC20 (Ethereum) BEP20 (BNB Chain)
TRC20 (Tron)
ERC20 (Ethereum)
BEP20 (BNB Chain)
Solana
Arbitrum
TRC20 (Tron)
ERC20 (Ethereum)
BEP20 (BNB Chain)
Solana
Arbitrum
TRC20 (Tron)
ERC20 (Ethereum)
BEP20 (BNB Chain)
Solana
Arbitrum
Show code
Blade
@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
Blade
<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.

Ben Carter
Priya Sharma[email protected]
Chloé Martin[email protected]

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