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

Options Format

The options prop accepts three formats — identical to the Combobox component:

{{-- 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'],
]"

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.

Livewire Binding

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

<x-wirekit::multi-select 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.

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') }}"></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.

Focus stays on the option you clicked rather than returning to the filter, so you can keep picking. 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

Accessibility

• 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
• 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
• Selected pills: each has a remove button with aria-label="Remove {label}"
• Empty state: "No results" message when the filter matches nothing
• Error state: aria-invalid="true" + aria-describedby linking to error message
• 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

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.
• Don't set :options to a list of plain strings. The component expects [{ value, label }] shape — strings render as objects with undefined value and break form submit.

Design Tokens

Customization

Override defaults in config/wirekit.php:

'components' => [
    'multi-select' => ['placeholder' => 'Choose...'],
],

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