Combobox

The mod.combobox() method automatically attaches event listeners for the specified HTML element (a <div class="mod-combobox"></div> tag) and handles search, keyboard navigation, and selection events for the element.

The combobox relies on children in the <ul> tag nested under the mod-combobox-dropdown-options for its data source. When an option is selected, the hidden .mod-combobox-value input has its value set to the selected option's data-value attribute's value.

The component features fuzzy search functionality using fuzzysort for intelligent filtering, keyboard navigation with arrow keys, and automatic dropdown management.

Optionally, a default_value can be passed via the options object which will automatically populate the hidden input's value and select the corresponding item with a matching data-value attribute in the list.

// Using mod(-plus).iife.min.js
window.mod.combobox(element: HTMLElement, options: object);

// Using mod(-plus).esm.min.js
import { combobox } from 'path/to/mod(-plus).esm.min.js';
combobox(element: HTMLElement, options: object);

Usage Examples

Use the following usage examples to guide your implementation.

<div class="mod-combobox">
  <input class="mod-combobox-value" type="hidden" name="state" value="AK" />
  <div class="mod-combobox-select">
    <p>Select a State</p>
    <i class="mod-icon-chevron-down"></i>
  </div>
  <div class="mod-combobox-dropdown">
    <header>
      <i class="mod-icon-search"></i>
      <input class="mod-input" placeholder="Search" />
    </header>
    <div class="mod-combobox-dropdown-options">
      <ul>
        <li data-value="AL">Alabama</li>
        <li data-value="AK">Alaska</li>
        <li data-value="AZ">Arizona</li>
        <li data-value="AR">Arkansas</li>
        <li data-value="CA">California</li>
        <li data-value="CO">Colorado</li>
        <li data-value="CT">Connecticut</li>
        <!-- Rest of options for combobox... -->
      </ul>
    </div>
  </div>
</div>

const element = document.body.querySelector('.mod-combobox');
const combobox_instance = window.mod.combobox(element, {
  default_value: 'AK',
  min_characters: 1,
  max_items: 10,
  events: {
    on_select_item: (value, event, selected_node) => {
      console.log('on_select_item', { value, selected_node, event });
    },
    on_clear_search: () => {
      console.log('on_clear_search');
    }
  }
});

// Programmatically set a selected value
combobox_instance.set_selected('CA');

API

element HTMLElement required

The container element that must contain elements with classes: 'mod-combobox-select' (with a

element), 'mod-combobox-dropdown' (with 'mod-input' and

elements).

options object

Configuration options for the combobox functionality.

default_value string

The default selected value for the combobox. Should match one of the data-value attributes in the list.

min_characters number

Minimum number of characters required before filtering search results.

max_items number

Maximum number of items to show in the dropdown after filtering.

events object

Event callbacks for various combobox actions.

on_select_item function

Callback function when an item is selected. Receives (value, event, selected_node) as parameters where value is the data-value attribute, event is the triggering event, and selected_node is the selected DOM element.

on_clear_search function

Callback function when the search input is cleared.