Lookup

<x-bt-lookup />

An autocomplete/combobox input that filters a dropdown of options as you type. Supports simple arrays, object arrays, key-value pairs, Eloquent collections, icons, clearable, Livewire binding, and slot integration.
Customize via presets →

Shared presets

This component shares all presets and styling options with the x-bt-input component.

Basic Usage

Pass an array of scalar values. Each value is used as both the label and the stored value.

Country

1<x-bt-lookup
2    label="Country"
3    placeholder="Search countries..."
4    :options="['Argentina', 'Brazil', 'Canada', 'France', 'Germany']"
5/>

Options Formats

The lookup normalizes all data shapes into [{id, name}] pairs internally.

Associative Array

Keys become the stored value, array values become the display label.

Country

 1<x-bt-lookup
 2    label="Country"
 3    placeholder="Search..."
 4    :options="[
 5        'ar' => 'Argentina',
 6        'br' => 'Brazil',
 7        'cl' => 'Chile',
 8        'uy' => 'Uruguay',
 9    ]"
10/>

Object Array

Use option-label and option-value to map fields from arrays or objects.

City

 1<x-bt-lookup
 2    label="City"
 3    placeholder="Search cities..."
 4    :options="[
 5        ['code' => 'NYC', 'title' => 'New York City'],
 6        ['code' => 'LON', 'title' => 'London'],
 7        ['code' => 'TKY', 'title' => 'Tokyo'],
 8    ]"
 9    option-label="title"
10    option-value="code"
11/>

Eloquent Collection

Pass an Eloquent collection with option-label and option-value to map model attributes.

User

1<x-bt-lookup
2    label="User"
3    placeholder="Search users..."
4    :options="$users"
5    option-label="name"
6    option-value="id"
7/>

Key-Value Pairs

Single key-value pair arrays where the key becomes the value and the value becomes the label.

Language

1<x-bt-lookup
2    label="Language"
3    placeholder="Search languages..."
4    :options="[['en' => 'English'], ['es' => 'Spanish'], ['fr' => 'French']]"
5/>

Icons

Place icons at the start or end of the input.

Select

Both

1<x-bt-lookup label="Search" icon-start="magnifying-glass" :options="$countries" placeholder="Search..." />
2<x-bt-lookup label="Select" icon-end="chevron-down" :options="$countries" placeholder="Pick one..." />
3<x-bt-lookup label="Both" icon-start="magnifying-glass" icon-end="chevron-down" :options="$countries" placeholder="Search..." />

Clearable

A clear button is shown by default when the input has a value. Disable it with :clearable="false".

Clearable (default)

Not Clearable

1<x-bt-lookup label="Clearable (default)" :options="$countries" placeholder="Type to search..." />
2<x-bt-lookup label="Not Clearable" :clearable="false" :options="$countries" placeholder="Type to search..." />

Sizes

Extra Small

Small

Medium (default)

Large

Extra Large

1<x-bt-lookup xs label="Extra Small" :options="$countries" />
2<x-bt-lookup sm label="Small" :options="$countries" />
3<x-bt-lookup label="Medium (default)" :options="$countries" />
4<x-bt-lookup lg label="Large" :options="$countries" />
5<x-bt-lookup xl label="Extra Large" :options="$countries" />

Colors

Color affects the border and ring on focus. Uses the input preset colors.

Default (beartropy)

Blue

Red

Green

Purple

1<x-bt-lookup label="Default (beartropy)" :options="$countries" />
2<x-bt-lookup blue label="Blue" :options="$countries" />
3<x-bt-lookup red label="Red" :options="$countries" />
4<x-bt-lookup green label="Green" :options="$countries" />
5<x-bt-lookup purple label="Purple" :options="$countries" />

Dynamic colors

Set the color dynamically: <x-bt-lookup :color="$hasError ? 'red' : 'primary'" />

All available colors

primary, beartropy, red, blue, green, yellow, purple, pink, gray, orange, amber, lime, emerald, teal, cyan, sky, indigo, violet, rose, fuchsia, slate, stone, zinc, neutral.

Slots

Place custom content before or after the input field. Chrome (borders, shadows) is automatically stripped.

Start Slot

1<x-bt-lookup label="Search" :options="$countries" placeholder="Search...">
2    <x-slot:start>
3        <span class="flex items-center px-2 text-gray-400">
4            <x-bt-icon name="globe-alt" class="w-5 h-5" />
5        </span>
6    </x-slot:start>
7</x-bt-lookup>

End Slot

1<x-bt-lookup label="Search" :clearable="false" :options="$countries" placeholder="Search...">
2    <x-slot:end>
3        <x-bt-button color="blue">Go</x-bt-button>
4    </x-slot:end>
5</x-bt-lookup>

Both Slots

1<x-bt-lookup label="Search" :clearable="false" :options="$countries" placeholder="Search...">
2    <x-slot:start>
3        <x-bt-button color="gray" soft>Scope</x-bt-button>
4    </x-slot:start>
5    <x-slot:end>
6        <x-bt-button color="blue">Search</x-bt-button>
7    </x-slot:end>
8</x-bt-lookup>

Livewire Integration

When bound with wire:model, the lookup keeps the text input and stored value separated. The user types and selects by label, while Livewire receives the corresponding option-value.

Deferred Binding

User

1<x-bt-lookup
2    id="lookup-user-deferred"
3    wire:model="userId"
4    label="User"
5    placeholder="Search users..."
6    :options="$users"
7    option-label="name"
8    option-value="id"
9/>

Live Binding

Use wire:model.live to update the Livewire property immediately on selection.

User (live)

Selected ID: none

 1<x-bt-lookup
 2    id="lookup-user-live"
 3    wire:model.live="liveUserId"
 4    label="User (live)"
 5    placeholder="Type to search..."
 6    :options="$users"
 7    option-label="name"
 8    option-value="id"
 9/>
10<p class="text-sm text-gray-500 mt-2">Selected ID: <strong>{{ $liveUserId ?? 'none' }}</strong></p>

Validation Errors

Errors are automatically detected from the Laravel validation error bag using the wire:model name. You can also force an error with customError.

Auto Validation

Submit without selecting a user to see the error. The border turns red and the error message appears below.

User

 1<x-bt-lookup
 2    id="lookup-validated"
 3    wire:model="validatedUser"
 4    label="User"
 5    placeholder="Select a user..."
 6    :options="$users"
 7    option-label="name"
 8    option-value="id"
 9/>
10<x-bt-button wire:click="submitUser" solid blue class="mt-3">Submit</x-bt-button>

Custom Error

Force an error state regardless of validation using customError.

Help Text

Use help or its alias hint to display text below the input.

Country

Start typing to see matching results.

Country

Select from the dropdown or type a custom value.

1<x-bt-lookup label="Country" help="Start typing to see matching results." :options="$countries" />
2<x-bt-lookup label="Country" hint="Select from the dropdown or type a custom value." :options="$countries" />

Disabled & Readonly

Disabled

Readonly

1<x-bt-lookup label="Disabled" :disabled="true" :options="$countries" />
2<x-bt-lookup label="Readonly" :readonly="true" value="Pre-filled" :options="$countries" />

Full keyboard navigation with diacritic-insensitive filtering.

Key	Action
Arrow Down	Move highlight down
Arrow Up	Move highlight up
Enter	Select highlighted option
Tab	Confirm current selection
Escape	Close dropdown

Typing filters options in real-time. Filtering is diacritic-insensitive (e.g., "cafe" matches "cafe"). Navigation wraps circularly.

Real-World Example

A location search form combining a lookup with an input and button.

City

Address

 1<div class="max-w-md space-y-4">
 2    <x-bt-lookup
 3        label="City"
 4        placeholder="Search cities..."
 5        icon-start="map-pin"
 6        :options="$countries"
 7    />
 8    <x-bt-input label="Address" placeholder="Enter your street address..." icon-start="home" />
 9    <x-bt-button solid blue class="w-full">Save Location</x-bt-button>
10</div>

Slot	Description
`start`	Content before the input field. Chrome (borders, shadows) is automatically stripped.
`end`	Content after the input field and built-in controls. Chrome is automatically stripped.

Prop	Type	Default	Description
`id`	`string\|null`	`auto-generated`	Element ID. Auto-generated as `beartropy-lookup-{uniqid}` if not provided.
`name`	`string\|null`	`same as id`	Hidden input name for form submission.
`label`	`string\|null`	`null`	Label text above the input.
`placeholder`	`string\|null`	`null`	Placeholder text for the search input.
`options`	`array`	`[]`	Data source for suggestions. Accepts simple arrays, associative arrays, arrays of objects, key-value pairs, or Eloquent collections.
`optionLabel`	`string`	`name`	Key used for the display label in each option.
`optionValue`	`string`	`id`	Key used for the stored value in each option.
`value`	`mixed`	`null`	Initial input value.
`color`	`string\|null`	`config default`	Color preset name. Uses the `input` preset colors.
`size`	`string\|null`	`md`	Size preset: `xs`, `sm`, `md`, `lg`, `xl`.
`iconStart`	`string\|null`	`null`	Icon name at the start of the input.
`iconEnd`	`string\|null`	`null`	Icon name at the end of the input.
`clearable`	`bool`	`true`	Show clear button when the input has a value. Clears both the visible text and the hidden Livewire value.
`disabled`	`bool`	`false`	Disables the input.
`readonly`	`bool`	`false`	Makes the input read-only.
`help`	`string\|null`	`null`	Help text below the input.
`hint`	`string\|null`	`null`	Alias for `help`. `help` takes precedence.
`customError`	`mixed`	`null`	Custom error message (bypasses the validation error bag).

Code highlighting provided by Torchlight

Current version: 1.0.7

Basic Usage

Options Formats

Associative Array

Object Array

Eloquent Collection

Key-Value Pairs

Icons

Clearable

Sizes

Colors

Slots

Start Slot

End Slot

Both Slots

Livewire Integration

Deferred Binding

Live Binding

Validation Errors

Auto Validation

Custom Error

Help Text

Disabled & Readonly

Keyboard Navigation

Real-World Example

Slots

Props

Basic Usage

Options Formats

Associative Array

Object Array

Eloquent Collection

Key-Value Pairs

Icons

Clearable

Sizes

Colors

Slots

Start Slot

End Slot

Both Slots

Livewire Integration

Deferred Binding

Live Binding

Validation Errors

Auto Validation

Custom Error

Help Text

Disabled &amp; Readonly

Keyboard Navigation

Real-World Example

Slots

Props

Disabled & Readonly