Searchable Dropdown Select With Search Box

Live examples of each type. Click a select to open it, then type to filter the options.

Basic searchable select

A standard dropdown with a search box. Start typing to filter a long list of options.

Grouped options (optgroup)

Options organized under non-selectable group headers using native <optgroup> elements.

Clearable selection

A clear button appears once a value is chosen, resetting the selection back to the placeholder.

Pre-selected value

A select that already has a value chosen on load, shown in the control.

Disabled select

A non-interactive control that cannot be opened, mirroring a disabled native select.

The library includes many advanced features commonly found in premium select components:

• Type-to-search filtering with match highlighting (<mark>)
• Full keyboard support:
• • Closed + focused: ArrowUp / ArrowDown step the value like a native <select> (no popup)
  • Open: ArrowUp / ArrowDown move the highlight, Enter selects, Escape closes
• Enter / Space / Alt+ArrowDown open the search panel
• Native change event and onChange / onOpen / onClose callbacks
• Works with any number of selects on one page
• Accessible - ARIA combobox / listbox pattern with live aria-activedescendant
• Progressive enhancement - the real <select> is kept for form submission
• Respects disabled options and disabled selects
• Mobile-aware - skips search auto-focus on touch devices so the keyboard does not cover the list
• Handles duplicate values, placeholder vs clearable empty options, and form reset
• Programmatic API: open(), close(), refresh(), destroy()
• React-ready (bundled component + destroy() for clean unmount)
• Accepts a CSS selector string or a DOM element
• Namespaced hcg-select-* classes (no style collisions), themeable via CSS variables
• Pure vanilla JS, zero dependencies, modern ES2015+

Install it with npm, load it from a CDN, or download the files directly and host them yourself. Once included, simply apply the library to a standard HTML <select> element to instantly add search functionality, keyboard navigation, and an improved user experience without changing your existing form structure.

npm install hcg-searchable-select

import hcgSelect from "hcg-searchable-select";
import "hcg-searchable-select/hcg-select.css";

hcgSelect("#country");

<!-- jsDelivr -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/hcg-searchable-select@1/hcg-select.css">
<script src="https://cdn.jsdelivr.net/npm/hcg-searchable-select@1/hcg-select.js"></script>

<!-- unpkg -->
<link rel="stylesheet" href="https://unpkg.com/hcg-searchable-select@1/hcg-select.css">
<script src="https://unpkg.com/hcg-searchable-select@1/hcg-select.js"></script>

Browse the source code on GitHub or package from npm.

1. Include the files

<link rel="stylesheet" href="hcg-select.css">
<script src="hcg-select.js"></script>

2. Add a select

Add the data-hcg-select attribute. It is auto-initialized on page load.

<select id="country" data-placeholder="Select a country" data-hcg-select>
  <option value="">- Select a country -</option>
  <option value="in">India</option>
  <option value="us">United States</option>
  <option value="uk">United Kingdom</option>
</select>

That's it. The widget reads the options, hides the native select, and renders a searchable dropdown.

Manual initialization

For selects added dynamically, or to pass options:

hcgSelect("#country", {
  placeholder: "Select a country",
  searchPlaceholder: "Type to search...",
  noResultsText: "Nothing found"
});

hcgSelect accepts a CSS selector string or a DOM element, and returns an API:

const api = hcgSelect(document.getElementById("country"));
api.open();           // open the panel
api.close();          // close the panel
api.refresh();        // rebuild the list from the current <option>s, then re-sync label + disabled state
api.disable();        // disable the widget (sets the native select.disabled = true)
api.enable();         // enable the widget
api.setDisabled(b);   // set disabled state from a boolean
api.destroy();        // tear down the widget and restore the original native <select>
api.element;          // the wrapper element
api.select;           // the underlying <select>

disable() / enable() / setDisabled() set the native select.disabled (the single source of truth), so the widget, the native element, and your forms never disagree. Setting select.disabled directly works too - a MutationObserver keeps the widget in sync either way.

Call api.refresh() after you add, remove, rename, disable, enable, or reorder the native <option>s (or toggle the select own disabled) so the widget stays in sync.

hcg-searchable-select includes a flexible set of configuration options that allow you to customize placeholders, search behavior, focus handling, messages, and event callbacks. These settings make it easy to adapt the dropdown to different user experiences while keeping the API simple and developer-friendly.

You have two ways to react when the user picks an option - use whichever fits.

1. Native change event (works with any framework / form code)

The underlying native <select> always holds the current value and fires a bubbling change event when the user picks an option:

document.getElementById("country").addEventListener("change", function () {
  console.log(this.value);
});

2. Callback options

Pass callbacks when you initialize manually:

hcgSelect("#country", {
  onChange: function (value, option, select) {
    console.log("picked", value, option.text);
  },
  onOpen:  function (select, api) { /* panel opened */ },
  onClose: function (select, api) { /* panel closed */ }
});

onChange receives the new value, the selected <option> element, and the <select>. It fires after the native change event, so both mechanisms stay in sync.

Native <optgroup> elements are rendered as non-selectable group headers, with indented options grouped beneath them.

<select data-hcg-select>
  <option value="">- Pick food -</option>
  <optgroup label="Fruits">
    <option value="apple">Apple</option>
    <option value="mango">Mango</option>
  </optgroup>
  <optgroup label="Drinks">
    <option value="tea">Tea</option>
  </optgroup>
</select>

Add data-clearable (or pass clearable: true) to show a clear button. Because a native select always has a value, clearing returns the selection to the placeholder option, so a placeholder must be present.

<select data-hcg-select data-clearable data-placeholder="Choose a city" id="city">
  <option value="">- Choose a city -</option>
  <option value="par">Paris</option>
  <option value="tok">Tokyo</option>
</select>

JavaScript usage:

hcgSelect("#city", {
  clearable: true
});

When the control is focused and closed, arrow keys step through options like a native select, and typing performs type-ahead. When open, arrow keys move the highlight, Enter selects, Escape closes, and Home or End jump to the first or last option.

hcg-searchable-select follows the ARIA combobox and listbox pattern, exposing roles, aria-expanded, aria-activedescendant, and aria-selected so screen readers announce navigation correctly.

On touch devices the search input is not auto-focused when the dropdown opens, so the on-screen keyboard does not cover the options list. Users can scroll and tap an option, or tap the search box to start filtering.

The core is framework-agnostic vanilla JS, so it works in React via a ref + useEffect. The destroy() API method makes mount/unmount clean.

Option A: use the bundled component

import { useState } from "react";
import HcgSelect from "hcg-searchable-select/react/HcgSelect.jsx";
import "hcg-searchable-select/hcg-select.css";

function Example() {
  const [country, setCountry] = useState("in");
  return (
    <HcgSelect value={country} onChange={setCountry} placeholder="Select a country">
      <option value="">- Select a country -</option>
      <option value="in">India</option>
      <option value="us">United States</option>
      <option value="uk">United Kingdom</option>
    </HcgSelect>
  );
}

onChange receives (value, option, select). Changing value or the <option> children re-syncs the widget automatically.

Option B: wrap it yourself

import { useEffect, useRef } from "react";
import hcgSelect from "hcg-searchable-select";
import "hcg-searchable-select/hcg-select.css";

function CountrySelect({ value, onChange }) {
  const ref = useRef(null);
  const apiRef = useRef(null);

  useEffect(() => {
    apiRef.current = hcgSelect(ref.current, {
      onChange: (val) => onChange(val)
    });
    return () => apiRef.current && apiRef.current.destroy(); // clean unmount
  }, []);

  useEffect(() => {
    if (ref.current && ref.current.value !== value) {
      ref.current.value = value;
      apiRef.current.refresh();
    }
  }, [value]);

  return (
    <select ref={ref} defaultValue={value} data-placeholder="Select a country">
      <option value="">- Select a country -</option>
      <option value="in">India</option>
      <option value="us">United States</option>
    </select>
  );
}

Always call api.destroy() in the effect cleanup so React can unmount theoriginal <select> without leaving the generated wrapper behind.

hcg-searchable-select works in all modern browsers, including Chrome, Firefox, Safari, and Edge.

hcg-searchable-select is open source and MIT licensed, created by HTML Code Generator.