Select Search

Select Search is a lightweight Drupal 10/11 module that enhances <select> elements with a searchable combobox interface.
It transforms long option lists into user-friendly searchable inputs, making them easier to use in both admin interfaces and front-end forms.

---

Features

• Combobox Mode (default): Replaces select elements with a searchable text input and dropdown list.
• Two search modes:
  • Substring search (default, fast, no dependencies).
  • Fuzzy search (optional, powered by Fuse.js).
• Smart empty option handling: Automatically removes "- None -" labels for cleaner interfaces.
• Works with:
  • Core Form API selects (#type => 'select').
  • Field widgets (via Select (with search) widget).
  • Views exposed filters.
  • select_or_other contrib module widgets.
• Accessibility features:
  • ARIA combobox attributes for screen readers.
  • Keyboard navigation preserved.
  • Proper focus management.
• User experience enhancements:
  • Clear button to reset search.
  • "No matches" message when filtering returns nothing.
  • Highlighting of matched text in dropdown.
  • Debounced input for performance.
  • Optgroup support (groups hidden if all children hidden).
• No-JS fallback: Form still works normally without JavaScript.

---

Installation

1. Place the module in web/modules/custom/select_search.

2. Enable the module:

   drush en select_search
   drush cr

3. (Optional) Download fuse.min.js (v6+) and place it into select_search/assets/js/
   if you want fuzzy search support.

---

Configuration

Navigate to:

Configuration → User interface → Select Search

Here you can set defaults:

• Auto-enable in admin forms
• Use fuzzy search by default
• Enable combobox mode by default (recommended)
• Minimum characters before filtering
• Search placeholder text
• Show clear button
• Show "No matches" message
• Debounce delay (ms)
• Highlight matched text

Available Properties

When using #select_search => TRUE, you can customize with these properties:

• #select_search_combobox - Enable combobox mode (default: TRUE)
• #select_search_fuzzy - Use fuzzy search instead of substring
• #select_search_min_chars - Minimum characters before filtering starts
• #select_search_placeholder - Placeholder text for search input
• #select_search_show_clear - Show clear (×) button
• #select_search_show_no_matches - Show "No matches" message
• #select_search_debounce_ms - Debounce delay in milliseconds
• #select_search_highlight - Highlight matched text in results

A Configure link is also available on the Extend page.

---

Usage

1. Form API (per element)

Opt-in with the #select_search property:

$form['job_role'] = [
  '#type' => 'select',
  '#title' => t('Job role'),
  '#options' => $allowed_values,
  '#empty_option' => '', // Will be automatically blanked for cleaner UI
  '#select_search' => TRUE,
  '#select_search_fuzzy' => TRUE, // Optional: enables Fuse.js fuzzy search
  '#select_search_combobox' => TRUE, // Default: enables combobox mode
  '#select_search_placeholder' => t('Search roles…'),
];

2. CSS class opt-in

$form['job_role']['#attributes']['class'][] = 'select-search';

3. Views exposed filters

Add select-search class in a hook_form_views_exposed_form_alter():

function MYMODULE_form_views_exposed_form_alter(&$form, $form_state) {
  foreach ($form as &$el) {
    if (is_array($el) && ($el['#type'] ?? NULL) === 'select') {
      $el['#attributes']['class'][] = 'select-search';
    }
  }
}

4. Field widget (admin friendly)

• Go to Structure → Content types → [Your type] → Manage form display.
• For your List (text) / List (integer) field, change the widget to Select (with search).
• Click the gear ⚙️ to adjust fuzzy search, min chars, placeholder, etc.

---

Development notes

• The JavaScript uses a Drupal behavior to scan for selects marked for enhancement (#select_search or .select-search).
• Combobox mode (default): Original select is hidden and replaced with a text input + dropdown list for better UX.
• Empty option handling: The module automatically detects and blanks "- None -" style empty options, especially for specific fields like field_job_title.
• Filtering creates a virtual dropdown list that shows/hides based on search input.
• With highlighting enabled, matched text is wrapped in <mark> tags in the dropdown.
• For large selects (thousands of options), use a debounce delay ≥120ms.
• Accessibility: Proper ARIA attributes are applied for combobox interaction patterns.

---

Limitations

• <select> elements with extremely large option counts (10k+) may still be slow.
• Highlighting inside dropdown may not render consistently in all browsers/themes.
• Does not replace advanced autocomplete widgets like Chosen or Select2; this is meant to be a lightweight, native select enhancement.

---

License

GPL-2.0+ (same as Drupal core).

---

Credits

• Concept & scaffolding: [Lawrence Monk]
• Development: Custom Drupal module, powered by Drupal behaviors and Fuse.js (for fuzzy search).
• Enhanced with combobox mode and smart empty option handling for improved user experience.
• Inspired by the need to make long select lists easier to use.

---