<x-widget.search>
Search Blade component for Laravel and Livewire
A search box that fills itself from the query string, in two sizes, with a clear button, the icon at either end and an optional keyboard shortcut. With suggest-url it suggests as you type, like a store's search: from your own endpoint, with details, links straight to a page, and groups. It searches as you type in a table's filters slot or with Livewire's wire:model.live; on its own it submits its form.
php artisan bladewell:add search
- Also adds
- Icon
- Used by
- Phone, Select, Table
- Works with
- Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+
- Guides
- Laravel data table with sorting, filters, pagination · Laravel searchable select that loads from the database
Usage
Suggestions endpoint
The URL in suggest-url answers GET ?q=… with JSON: a list, or a resource collection ({"data": [...]}). Each suggestion is a string, or a label with an optional value (what fills the box), meta, href (a page to open) and group. Keep it short, and throttle it: it runs as people type.
Route::get('/products/suggest', function (Request $request) {
$q = $request->validate(['q' => ['required', 'string', 'max:100']])['q'];
// It answers anyone, signed in or not: only what the store shows everyone, never drafts or hidden products.
return Product::query()
->where('is_published', true)
// % and _ typed match themselves, the same on every database (ESCAPE '!'), and LOWER() ignores case.
->whereRaw("LOWER(name) LIKE LOWER(?) ESCAPE '!'", ['%'.str_replace(['!', '%', '_'], ['!!', '!%', '!_'], $q).'%'])
// Each suggestion shows its category: loaded with them, not one query per result.
->with('category:id,name')
->orderBy('name')
->limit(8)
->get()
->map(fn (Product $product): array => [
'label' => $product->name,
'meta' => $product->category->name,
'href' => route('products.show', $product),
]);
})->middleware('throttle:120,1')->name('products.suggest');
Livewire
In a Livewire component, bind with wire:model.live (add .debounce.300ms to wait for a pause in typing); no name is needed. The box shows the property after every render, so clearing it in PHP empties it too, and the × button empties the property as if the text had been deleted. Filter in render(), with % and _ matching themselves and case ignored on every database: ->whereRaw("LOWER(name) LIKE LOWER(?) ESCAPE '!'", ['%'.str_replace(['!', '%', '_'], ['!!', '!%', '!_'], $this->search).'%']).
<div class="space-y-4">
<x-widget.search placeholder="Search customers" shortcut="/" wire:model.live.debounce.300ms="search" />
<ul>
@foreach ($customers as $customer)
<li wire:key="{{ $customer->id }}">{{ $customer->name }}</li>
@endforeach
</ul>
</div>
On the server
The search can't stop a request that skips it. Here's what to check on your server, and what to keep cheap.
Security
-
The
suggest-urlendpoint answers anyone who calls it, signed in or not. Scope results to what the person may see, and escape%and_in like queries, as the usage shows.OWASP: Insecure direct object references · OWASP: SQL injection
Server cost
-
The widget waits 200ms after typing, cancels stale requests and remembers answers, but it's still a request per pause. Throttle the route,
limit()the results (8 is plenty), considersuggest-minof 2 or 3 on big tables, index the column, and load what each suggestion shows with the results (with('category')), not one query per result. For large catalogues, full-text search (Scout) scales better thanlike '%…%'.Laravel: Rate limiting routes · Laravel: Scout · Laravel: Eager loading
-
Popular queries repeat. Consider caching each answer for a minute or two with
Cache::remember(), keyed by the query and by everything that decides what the person may see: the user, and the active workspace or team if visibility depends on it, so switching workspaces never shows the last one's results. Clear those entries when someone's access changes, or don't cache suggestions that depend on permissions at all.
Examples
Suggestions
suggest-url lists suggestions as you type, after two characters (suggest-min). The arrow keys move through them and Enter takes one, filling the box; in a form, it then searches. Try "wire" or "desk".
Show code Hide code
<x-widget.search name="q" placeholder="Search products" class="max-w-md" suggest-url="{{ route('products.suggest') }}" />
Keyboard shortcut
shortcut="/" jumps to the box from anywhere on the page, as on GitHub: press / (not while typing in another field). The key shows as a hint while the box is empty and unfocused, and screen readers hear it from aria-keyshortcuts.
Show code Hide code
<x-widget.search name="docs" placeholder="Search the docs" shortcut="/" class="max-w-md" />
Suggestions with details
A suggestion can carry small text at the end (meta): a category, a price, a count. The typed text is shown in bold. Try "key".
Show code Hide code
<x-widget.search name="q" placeholder="Search products" class="max-w-md" suggest-url="{{ route('products.suggest', ['style' => 'details']) }}" />
Suggestions that open a page
A suggestion with an href opens that page when chosen, instead of searching: a store's product, a docs article. Try "phone".
Show code Hide code
<x-widget.search name="q" placeholder="Search products" class="max-w-md" suggest-url="{{ route('products.suggest', ['style' => 'links']) }}" />
Grouped suggestions
Suggestions with a group are listed under its heading, in the order the groups first appear. Try "wireless".
Show code Hide code
<x-widget.search name="q" placeholder="Search products" class="max-w-md" suggest-url="{{ route('products.suggest', ['style' => 'grouped']) }}" />
Search form
In a GET form, Enter submits and the page reloads with ?q=…; the box fills itself back in from the query string, so the results can be shared and bookmarked. That's all it does on its own. To search as you type without a reload, put it in a table's filters slot, or bind it with wire:model.live in Livewire.
Show code Hide code
<form method="GET" role="search" class="flex max-w-md items-center gap-2">
<x-widget.search name="q" placeholder="Search the help centre" label="Search the help centre" />
<button type="submit" class="bg-primary-fill text-on-primary focus-visible:ring-primary h-12 shrink-0 rounded-[20px] px-5 text-sm font-medium outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-surface">Search</button>
</form>
Icon at the start
icon-position="start" puts the magnifier before the text. value fills it in (the query string wins, when it has one); :clearable="false" leaves out the × button.
Show code Hide code
<div class="flex flex-col gap-4">
<x-widget.search name="team" placeholder="Search people" icon-position="start" />
<x-widget.search name="team_fixed" value="Design" icon-position="start" :clearable="false" size="sm" class="max-w-xs" />
</div>
Sizes and widths
size sets the height, matching the button and field sizes: sm (32px) beside compact controls, md (48px, the default) beside form fields. The width is the layout's: the box fills its container, so narrow it with a class such as max-w-xs. The × clears the text.
Show code Hide code
<div class="flex flex-col gap-4">
<x-widget.search name="find" placeholder="Search transactions" />
<x-widget.search name="find_small" placeholder="Small search" size="sm" />
<x-widget.search name="find_narrow" placeholder="Narrow search" class="max-w-xs" />
</div>
Props
Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.
<x-widget.search>
| Prop | Default | Description |
|---|---|---|
| name |
null
|
What it submits as; its error and old input are found under it. Optional with wire:model, which then names it. |
| id |
null
|
Defaults to one made from the name (or the wire:model property). |
| value |
null
|
Defaults to the query string under the name, so a search form fills back in; or the bound Livewire property. |
| placeholder |
'Search'
|
Shown while it's empty. |
| label |
null
|
Its name for screen readers; defaults to the placeholder. |
| size |
'md'
|
sm (32px) or md (48px). |
| clearable |
true
|
An × button, shown while there's text, that empties the box. It fires input and change, so whatever listens (a table's filters, wire:model) reacts as if the text had been deleted. |
| icon-position |
'end'
|
Where the magnifier sits: end (after the text) or start (before it). |
| shortcut |
null
|
A key that jumps to the box from anywhere on the page, e.g. "/", shown as a hint while the box is empty and unfocused. One character, without modifiers; it doesn't fire while you're typing in another field. |
| suggest-url |
null
|
Suggestions as you type, like a store's search: a URL that answers GET ?q=… with JSON, a list or {"data": [...]}. Each suggestion is a string, or ['label' => …, 'value' => what fills the box, 'meta' => small text at the end, 'href' => a page to open instead, 'group' => a heading to list it under]. |
| suggest-min |
2
|
How many characters to type before asking for suggestions. |
| messages |
[]
|
Rewords what screen readers hear about the suggestions, by key: count (:count), none, failed. |
Accessibility
All 8 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 search 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/search/index.blade.php Show
resources/js/widget/search/index.js Show
app/View/Widget/ElementIds.php Show
app/View/Widget/FormField.php Show