Use the shared searchable select

POM provides one frontend searchable-select implementation for theme forms, Faceted Search, WooCommerce, and compatible extensions. It is written in native JavaScript and supports local choices, multiple selection, keyboard navigation, and AJAX result loading.

Enqueue the supported asset

Call the shared helper when the current frontend view contains a searchable select:

pom_enqueue_searchable_select_assets();

This enqueues the pom-searchable-select script and style handles. The style handle normally depends on web-main-style: searchable-select structure and appearance are compiled once into the generated theme stylesheet instead of loading the fixed Select2 palette on the frontend. On the frontend, the historical select2 and selectWoo handles resolve to this asset, so extensions can retain those dependencies while migrating to the native API. WordPress administration screens are not replaced.

The alias resolver checks the complete registered dependency path before replacing a legacy handle. If an integration has pointed one of the replacement's dependencies back to select2 or selectWoo, POM removes that back-reference from the theme-owned replacement before creating the alias. This preserves the native replacement while preventing a recursive dependency graph. Extensions should still keep their graph unidirectional: an integration stylesheet may depend on select2, but web-main-style must not depend on that integration stylesheet or on the legacy alias.

Searchable selects use the same normal and alternate form settings as the other controls. Input background, borders, radius, typography, dropdown background, dropdown text, and highlighted-option background therefore follow the corresponding Forms settings, including forms_styles_pom_forms_inputs_dropdowns_bg_color. Regenerate the theme CSS after changing those settings, as with any other form appearance option.

The theme does not add jQuery as a dependency and does not expose jQuery.fn.select2, jQuery.fn.selectWoo, or any other jQuery compatibility facade. The historical WordPress handles are asset aliases only. Extensions must initialize and control searchable selects through the native PomSelect API.

Initialize a select

Pass a native HTMLSelectElement to PomSelect.init():

var select = document.querySelector('#customer');

window.PomSelect.init(select, {
  allowClear: true,
  placeholder: 'Search customers',
  width: '100%'
});

Declarative selects can use data-pom-select and are initialized automatically. Use PomSelect.get(select) to retrieve an existing instance, or call refresh() after changing the underlying options or selected values.

The dropdown stays inside its select container and opens above or below the control according to the available viewport space. Theme widgets containing PomSelect allow the menu to extend beyond the widget while retaining float containment. Custom wrappers must also allow visible overflow wherever the menu needs to extend. Verify opening, searching, selecting, and scrolling the options at desktop and mobile widths.

Load results with AJAX

The AJAX API follows the Select2 result contract so an existing endpoint can normally be reused:

window.PomSelect.init(select, {
  minimumInputLength: 2,
  ajax: {
    url: window.myIntegration.ajaxUrl,
    method: 'POST',
    delay: 250,
    data: function (params) {
      return {
        action: 'my_customer_search',
        nonce: window.myIntegration.nonce,
        q: params.term,
        page: params.page
      };
    },
    processResults: function (response) {
      return response.data;
    }
  }
});

Return results with id and text for every choice. Add pagination.more when another page is available:

{
  "results": [
    { "id": "42", "text": "Example customer" }
  ],
  "pagination": { "more": false }
}

WordPress responses wrapped as { "success": true, "data": ... } are also accepted. Requests use the Fetch API unless the integration supplies an ajax.transport function.

Replace the implementation

An integration can replace the script URL or add a dedicated stylesheet after the generated theme stylesheet with these filters:

• pom_searchable_select_script_uri
• pom_searchable_select_style_uri

The default value of pom_searchable_select_style_uri is empty because the supported frontend styles already live in web-main-style. A non-empty filtered URL is loaded after that stylesheet and should contain only intentional integration-specific overrides. The replacement script must preserve the PomSelect API. The select2 and selectWoo frontend aliases only resolve WordPress asset dependencies and do not provide jQuery methods. Do not use these filters to replace the separate Select2 copies used by WordPress administration or POM Framework settings fields.