Kaiko UI Kaiko UI

Combobox

Stable

Searchable dropdown component with single or multiple selection. Alpine.js state is managed in an external script — zero inline JavaScript in templates.

API Reference

Component Family

Component Description Key Attributes
c-combobox Main container. Wraps trigger + menu. Handles click-away and the clear button. placement, open
c-combobox.trigger Toggle button. Shares the same API as c-button. Updates label to reflect current selection. color, variant, size
c-combobox.menu Dropdown panel with integrated search input. placeholder, width
c-combobox.checkbox Multi-select item. Use inside c-combobox.menu for multiple selection. value, label, checked, disabled, name
c-combobox.radio Single-select item. Use inside c-combobox.menu for single selection. value, label, checked, disabled, name

c-combobox

Attribute Description Type Default
placement Position of the dropdown relative to the trigger string "bottom"
open Force the dropdown to render in its open state on initial render boolean False

c-combobox.trigger

Attribute Description Type Default
color Button color theme string ""
variant Button style variant string "default"
size Button size string "md"

selection-changed event

Event Description Detail
selection-changed Fired on select, deselect, or clear. Bubbles to parent containers. Array of selected values, e.g. ["python", "rust"]

placement values

bottom top left right bottom-start bottom-end top-start top-end

Accessibility

Keyboard navigation: the trigger opens the menu. Arrow keys navigate items; Enter selects; Escape closes the panel. Tab moves focus out of the combobox.

Search input: the integrated search field in c-combobox.menu receives focus automatically when the panel opens, reducing the number of keystrokes needed to filter items.

Selection announcement: item check/uncheck state changes are announced via the underlying checkbox/radio ARIA semantics.

Examples

Usage 


<c-combobox>
  <c-combobox.trigger color="primary">Select option</c-combobox.trigger>
  <c-combobox.menu>
    <c-combobox.radio name="option" value="a" label="Option A"></c-combobox.radio>
    <c-combobox.radio name="option" value="b" label="Option B"></c-combobox.radio>
  </c-combobox.menu>
</c-combobox>

Single Selection

Select option 
<c-combobox>
  <c-combobox.trigger color="primary">Select option</c-combobox.trigger>
  <c-combobox.menu>
    <c-combobox.radio name="option" value="profile" label="Profile"></c-combobox.radio>
    <c-combobox.radio name="option" value="settings" label="Settings"></c-combobox.radio>
    <c-combobox.radio name="option" value="logout" label="Logout"></c-combobox.radio>
  </c-combobox.menu>
</c-combobox>

Multiple Selection

Select technologies 
<c-combobox>
  <c-combobox.trigger color="secondary" variant="outline">Select technologies</c-combobox.trigger>
  <c-combobox.menu placeholder="Search technologies...">
    <c-combobox.checkbox name="tech[]" value="python" label="Python" checked></c-combobox.checkbox>
    <c-combobox.checkbox name="tech[]" value="javascript" label="JavaScript"></c-combobox.checkbox>
    <c-combobox.checkbox name="tech[]" value="rust" label="Rust"></c-combobox.checkbox>
  </c-combobox.menu>
</c-combobox>

Scrollable Menu (More Than 5 Items)

Select port 
<c-combobox>
  <c-combobox.trigger>Select port</c-combobox.trigger>
  <c-combobox.menu placeholder="Search ports...">
    <c-combobox.radio name="port" value="rotterdam" label="Rotterdam"></c-combobox.radio>
    <!-- more items... -->
  </c-combobox.menu>
</c-combobox>

Trigger Variants

Primary
Secondary Outline
Accent Soft (sm)
Ghost (sm) 
<c-combobox>
  <c-combobox.trigger color="secondary" variant="outline">Secondary Outline</c-combobox.trigger>
  <c-combobox.menu>...</c-combobox.menu>
</c-combobox>

Disabled Items

Choose framework 
<c-combobox>
  <c-combobox.trigger>Choose framework</c-combobox.trigger>
  <c-combobox.menu>
    <c-combobox.radio name="fw" value="django" label="Django"></c-combobox.radio>
    <c-combobox.radio name="fw" value="rails" label="Ruby on Rails" disabled></c-combobox.radio>
  </c-combobox.menu>
</c-combobox>

Reacting to Selection Changes 


<div @selection-changed="selectedValues = $event.detail">
  <c-combobox>
    <c-combobox.trigger>Select</c-combobox.trigger>
    <c-combobox.menu>
      <c-combobox.checkbox name="vals[]" value="a" label="Alpha"></c-combobox.checkbox>
      <c-combobox.checkbox name="vals[]" value="b" label="Beta"></c-combobox.checkbox>
    </c-combobox.menu>
  </c-combobox>
</div>

Server-Side Rendered Items 


<c-combobox>
  <c-combobox.trigger color="primary" variant="outline" size="sm">
    
  </c-combobox.trigger>
  <c-combobox.menu placeholder="Search...">
    {% for option in options %}
      <c-combobox.checkbox
        name="values[]"
        value="{{ option.id }}"
        label="{{ option.value }}"
        {% if option.id in selected_ids %}checked{% endif %}>
      </c-combobox.checkbox>
    {% endfor %}
  </c-combobox.menu>
</c-combobox>