Skip to content
Bladewell

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

PHP
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).'%']).

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

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), consider suggest-min of 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 than like '%…%'.

    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.

    Laravel: Cache

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