Multi-Select

The <x-wirekit::multi-select> component is a combobox that supports selecting multiple values. Selected items appear as removable pills inside the input area, and the dropdown filters options as the user types. It implements the WAI-ARIA 1.2 Combobox pattern with aria-multiselectable="true".

Basic Usage

<x-wirekit::multi-select
    name="countries"
    label="Countries"
    :options="[
        'de' => 'Germany',
        'fr' => 'France',
        'es' => 'Spain',
        'it' => 'Italy',
        'nl' => 'Netherlands',
        'at' => 'Austria',
        'ch' => 'Switzerland',
    ]"
    placeholder="Search countries..."
/>

With Preselected Values

<x-wirekit::multi-select
    name="skills"
    label="Skills"
    :options="[
        'php' => 'PHP',
        'js' => 'JavaScript',
        'py' => 'Python',
        'go' => 'Go',
        'rust' => 'Rust',
    ]"
    :value="['php', 'js']"
    placeholder="Add skills..."
/>

The value prop accepts an array of option keys that should be pre-selected on load.

Error State

<x-wirekit::multi-select
    name="tags-error-demo"
    label="Tags"
    :options="['a' => 'Alpha', 'b' => 'Beta', 'c' => 'Gamma']"
    error="Please select at least one tag."
/>

With Hint

<x-wirekit::multi-select
    name="roles"
    label="Roles"
    :options="['admin' => 'Admin', 'editor' => 'Editor', 'viewer' => 'Viewer']"
    hint="Assign one or more roles to this user."
/>

Width

Like all WireKit form components, the multi-select fills its container (w-full). Control the width via the parent element:

<div class="max-w-md">
    <x-wirekit::multi-select label="Tags" name="tags" :options="$tags" />
</div>

See Input — Width for more layout examples (grid columns, mixed widths).

Panel Placement and Width

The options panel opens below the field, aligned to its start, and exactly as wide as the field. Two props change that:

• placement sets where the panel opens: bottom-start (the default), bottom, bottom-end, top-start, top, top-end, left-start, left, left-end, right-start, right or right-end. When the chosen side has no room, the panel flips to the opposite one, and when aligning it to the field's end would push it off the screen, it aligns to the start instead. start and end follow the reading direction: in a right-to-left document, bottom-end aligns the panel with the field's left edge.
• panel-width sets how wide it is: trigger (the default) matches the field, auto takes the width of the widest option, and a CSS length such as 20rem sets one. A panel with auto or a length is never narrower than the field and never wider than the room its placement leaves.

A label wraps inside the panel rather than widening it. A name with no space or hyphen in it, the shape a repository name with underscores has, breaks inside the word where nothing else fits, so the list never has to scroll sideways.

A compact field with a wider panel suits options whose labels run longer than the field is wide:

<x-wirekit::multi-select
    name="notify"
    label="Notify"
    placement="bottom-end"
    panel-width="20rem"
    :options="['mentions' => 'Mentions and direct replies', 'reviews' => 'Review requests on your pull requests', 'releases' => 'Releases of watched repositories']"
/>

Icons, Avatars and Descriptions

An option can show an icon, an image or an avatar before its label, and a line of description under it. The open list shows all of it. A pill shows the chosen option's icon, image or avatar and its label, never the description, and a shorter selectedLabel when the option has one. The pill's remove button keeps the full label as its name:

<x-wirekit::multi-select
    name="notifications"
    label="Notifications"
    :value="['starred']"
    :options="[
        ['value' => 'all', 'label' => 'All activity', 'icon' => 'bell', 'description' => 'Every change in the projects you belong to.'],
        ['value' => 'starred', 'label' => 'Starred only', 'icon' => 'star', 'description' => 'Only the projects you have starred.'],
        ['value' => 'none', 'label' => 'Muted', 'icon' => 'mute', 'description' => 'No notifications at all.'],
    ]"
/>

An avatar is a photo drawn round. When a person has no photo, or the photo fails to load, the avatar shows their initials instead, so a list of people stays aligned whether or not everyone has uploaded one:

<x-wirekit::multi-select
    name="owner"
    label="Owner"
    :options="$people->map(fn ($person) => [
        'value' => $person->id,
        'label' => $person->name,
        'avatar' => $person->avatar_url,
        'description' => $person->email,
    ])->all()"
/>

The search matches an option's label, its selectedLabel and its keywords, ignoring case and accents (munchen finds "München"). It does not match the description: typing into the filter narrows the list to options whose name fits, and a sentence of context would match far more than the reader meant.

Options Format

The options prop accepts three formats, each normalized the way the Combobox normalizes it. (Combobox accepts a fourth, grouped shape; the multi-select does not group.)

{{-- Associative: key => label --}}
:options="['de' => 'Germany', 'fr' => 'France']"

{{-- List of strings (value === label) --}}
:options="['Apple', 'Banana', 'Cherry']"

{{-- List of arrays --}}
:options="[
    ['value' => 'de', 'label' => 'Germany'],
    ['value' => 'fr', 'label' => 'France'],
]"

A list is keys 0, 1, 2 … in order, and there each string is value and label at once. Any other array is a map whose key is submitted, integer keys included, so an id map from the database works as it reads:

{{-- An id map: the ids are submitted, not the names --}}
:options="Product::pluck('name', 'id')->all()"

A list you filtered keeps its keys (array_filter() leaves [0 => 'Apple', 2 => 'Cherry']) and is then read as a map, submitting 0 and 2. Pass it through array_values() to keep it a list.

An option written as an array can carry these keys beside value and label:

An option shows one of icon, image and avatar. Setting two of them, or initials without avatar, throws an InvalidArgumentException that names the option. So does a value that is not text, including an HtmlString: options are drawn in the browser as plain text, and markup would show up as literal tags.

A list of languages names each one in its own language, words the page is not written in. Give those options their lang:

<x-wirekit::multi-select
    name="languages"
    label="Languages you speak"
    :value="['de']"
    :options="[
        ['value' => 'de', 'label' => 'Deutsch', 'lang' => 'de'],
        ['value' => 'fr', 'label' => 'Français', 'lang' => 'fr'],
        ['value' => 'ja', 'label' => '日本語', 'lang' => 'ja'],
    ]"
/>

Form Submission

Each selected value is submitted via a hidden <input type="hidden" name="name[]">. This means Laravel receives a standard array — no special parsing needed on the backend. Write name="skills" or name="skills[]", as for a native multiple select; both submit skills[].

Livewire Binding

Bind the array of selected values with wire:model on the component tag:

<x-wirekit::multi-select label="Tags" wire:model.live="tags" name="tags" :options="$options" :value="$tags" />

The selection lives in Alpine and is exposed to the binding, so the property receives the full array on every pick and every removal. Pass the current value with :value as well — that seeds the initial selection, the same framework-agnostic pattern the other stateful controls use.

An array of ids, such as $product->tags->pluck('id')->all(), works as it is: the ids reach the multi-select as numbers while its options carry their values as text, and each id names its option, so its pill shows the label and the list no longer offers it.

In an Alpine component of your own, x-model on the tag binds the same array. See An x-model on a WireKit component.

Server Search

For a list too long to render into the page, a catalog with thousands of records for example, set server and search in your Livewire component. The field stops filtering in the browser. What the reader types is sent as a search-change event once they pause, and the options you render are the results:

{{-- 1. The results are the options; the event hands the typed text to your component --}}
<x-wirekit::multi-select
    server
    label="Products"
    name="productIds"
    wire:model="productIds"
    :options="$this->productResults['options']"
    :truncated="$this->productResults['truncated']"
    x-on:search-change="$wire.set('productSearch', $event.detail.value)"
/>

// 2. In the Livewire component
public string $productSearch = '';

public array $productIds = [];

#[Computed]
public function productResults(): array
{
    // 3. Before a search: the records already chosen, so their pills have a name on load
    if ($this->productSearch === '') {
        return ['options' => Product::whereIn('id', $this->productIds)->pluck('name', 'id')->all(), 'truncated' => false];
    }

    // 4. A search: ask for one more than you show, and say so when it came back
    $hits = Product::search($this->productSearch)->take(21)->get();

    return ['options' => $hits->take(20)->pluck('name', 'id')->all(), 'truncated' => $hits->count() > 20];
}

What the field does with that:

• It sends only what is worth a query. The text goes out once it has at least searchMinLength characters (2 by default) and the reader has paused for searchDebounce milliseconds (300 by default), and only when it differs from the last search. Shorter text sends an empty value once, so your component can go back to what it lists before a search.
• It says when it is waiting. From the moment the request carrying a search leaves until it comes back, with a response, an error or a cancellation, or is lost when the connection drops, the list is marked busy and says "Searching…". $wire.set(…), as above, sends the request at once. A handler that holds it back leaves the list quiet after a second, because the wait has not begun.
• A chosen record keeps its name. Every option the field has been given is remembered by its value, so a pill still reads "Red shirt" after a search for socks has replaced the list it was chosen from. A value the field was never given an option for shows as the value itself, which is why step 3 returns the chosen records.
• The search text stays after a pick, so several results of one search can be chosen in a row.
• An empty list says what it means: "Type to search" before any search, "Type at least 2 characters" for shorter text, "No results" for a search that found nothing, and, with truncated, "More results. Keep typing to narrow them." under results cut at your limit. A polite live region reads the same status to a screen reader.
• A failed search says so. A search your server answers with an error, or one lost when the connection drops, says "Search failed. Try again." while its text is in the field, instead of the results of an earlier search or "No results", and the same text is sent again the next time the reader types or opens the list.

Options in server mode may carry an icon, an image, an avatar or a description like any other; each row draws what its own option carries. The event is the one the data table sends in its server mode, with the same { value } payload.

Results as a List With Checkboxes

With layout="list" the options are not in a dropdown. They stand open under a search field, each with a checkbox, and the choice is listed below them with a button to take each entry out. A chosen option stays in the list with its box checked, so several can be picked from one search in a row.

<x-wirekit::multi-select
    layout="list"
    label="Categories"
    name="categories"
    :options="[
        'shirts' => 'Shirts',
        'socks' => 'Socks',
        'jackets' => 'Jackets',
        'shoes' => 'Shoes',
    ]"
    :value="['socks']"
/>

It works with Server Search unchanged: the text is sent as search-change, the list says when it is searching and when your results were cut, and a chosen record keeps its name in the list below after the results have moved on to another search.

{{-- 1. The same server search, shown as a list --}}
<x-wirekit::multi-select
    server
    layout="list"
    label="Products"
    name="productIds"
    wire:model="productIds"
    :options="$this->productResults['options']"
    :truncated="$this->productResults['truncated']"
    x-on:search-change="$wire.set('productSearch', $event.detail.value)"
/>

Optimistic UI

Pass the name of the Livewire method the control should call and the pill appears — or disappears — immediately, then confirms or undoes itself when the server answers:

<x-wirekit::multi-select
    name="tags"
    label="Tags"
    :value="$tags"
    :options="['php' => 'PHP', 'js' => 'JavaScript', 'css' => 'CSS']"
    optimistic="saveTags"
/>

The method receives the full new selection as an array, not the value that changed:

public function saveTags(array $tags): void
{
    $this->tags = $tags;
}

Load wirekit-optimistic.js alongside whichever bundle you already use — below it, in your layout:

@wirekitScripts
<script src="{{ asset('vendor/wirekit/wirekit-optimistic.js') }}" defer></script>

Try it

The demo below runs the real path: the change shows immediately, the outline says it is provisional, and the server's answer either confirms it silently or takes it back.

{{-- In your app there is no host: your own Livewire component owns the method. --}}
<x-wirekit::multi-select
    name="tags"
    label="Tags"
    :value="$tags"
    :options="['php' => 'PHP', 'js' => 'JavaScript', 'css' => 'CSS']"
    optimistic="saveTags"
/>

The <livewire:demos.…> wrapper above exists only on this site — it supplies the demo methods so the page can show a real round trip. The block under it is what you write.

The list stays open after a pick, so you can keep picking, and a pick made with a mouse leaves the focus in the filter input. Removing a pill takes the same path as picking an option: it is the same server mutation, so it is undone the same way. The filter text is separate state and is never rolled back — an undo puts back the server's selection, never what you were typing.

Props

Slots

Accessibility

• The filter input carries autocomplete="off", so the browser's own suggestions do not open over the list. An autocomplete of yours does not apply there.
• An autofocus, inputmode, enterkeyhint, autocapitalize or spellcheck written on the tag goes to the filter input, where the browser and the on-screen keyboard read it.
• Filter input: role="combobox", aria-expanded, aria-controls, aria-autocomplete="list", aria-multiselectable="true"
• Listbox: role="listbox" with aria-multiselectable="true" and unique id linked via aria-controls
• Each option: role="option", aria-selected="true" / "false", and its own id
• The open list holds the options not chosen yet, and each says aria-selected="false". A choice leaves the list and shows as a pill in the field, where its remove button takes it back out. With layout="list" every option stays in the list, and its checkbox says whether it is chosen
• An option with a description is named by its label through aria-labelledby and described by the description through aria-describedby, so a screen reader announces the two apart instead of as one long name
• An option's icon, image or avatar is decorative (aria-hidden), in the list and in the pills, because the label already names the option. An avatar's initials are not read either
• Keyboard position: aria-activedescendant on the filter input names the active option. Focus stays in the input for the whole interaction — that is what makes a combobox a combobox — so this attribute is what tells a screen reader which option Enter would take. The option is tinted on screen. Under forced colors, where that tint is not painted, the option the arrow keys are on is framed with a dashed line in the system's selection color
• A press on an option with a mouse or a pen leaves the focus in the filter input, with and without optimistic, so the next Tab goes on from the field. The open list leaves with the focus: Tab closes it, so two multi-selects in a row never leave two lists standing
• Selected pills: each has a remove button with aria-label="Remove {label}". Pressing it moves the focus to the pill that takes its place, to the new last pill when the last one was removed, or to the search field once none is left, so the next Tab goes on from inside the field. The list of options stays closed through a removal, also when the search field takes the focus: it opens when the reader tabs or clicks into the field, types or presses an arrow key
• Empty state: "No results" message when the filter matches nothing
• Error state: aria-invalid="true" + aria-describedby linking to error message
• With layout="list": a search field (type="search", aria-controls naming the results) instead of the combobox, the results as a group of native checkboxes named by the field's label, each checkbox named by its option, and a remove button per chosen entry named "Remove {label}". A checkbox says its own state, so no separate announcer speaks the pick, and taking an entry out moves the focus to the remove button that takes its place, or to the search field once the list is empty, with optimistic set as well
• Selection changes announced via an aria-live="polite" region. With optimistic set, that region is not rendered and the optimistic layer announces the pick instead — one voice per change, so that hearing a second announcement always means something went differently

Keyboard Interaction

With layout="list" there is no listbox to open: Tab moves from the search field through the checkboxes, Space checks or unchecks the focused one, and Tab goes on to the remove buttons of the chosen entries, which Enter or Space presses.

Space types a space. It is not bound to anything here, and deliberately so: this is an editable combobox rather than a select-only one, and a text field that swallows the space bar cannot be typed into. Use Enter to toggle.

Pitfalls

• Don't use multi-select for binary on/off groups. A row of <x-wirekit::checkbox> is more discoverable. Multi-select is for moderate-to-large option lists where space is at a premium.
• A list of plain strings submits the string itself, not a separate key. That is the point of the shape, and it is what you want for free-form tags. When the value your backend stores differs from the text a person reads, use the associative key => label map or the array-of-arrays form instead — otherwise a renamed label silently changes the submitted value.

Design Tokens

Customization

Override defaults in config/wirekit.php:

'components' => [
    'multi-select' => ['placeholder' => 'Choose...', 'placement' => 'bottom-start', 'panel-width' => 'trigger', 'search-min-length' => 2, 'search-debounce' => 300],
],

Further Reading

• WAI-ARIA 1.2 Combobox Pattern — the authoring pattern this component implements
• MDN: role="combobox"
• MDN: role="listbox"
• MDN: aria-multiselectable
• MDN: aria-selected