Update v4.2 - New components, 10+ framework guides, and quality improvements. Visit Changelog

........ Github
Figma X (Twitter)

Tailwind CSS Combobox Plugin API

Headless, unstyled combobox plugin built with JavaScript and TypeScript, including installation, usage, options, methods, events, and selectors.

JavaScript Typescript

Installation

To get started, install Combobox plugin via npm, else you can skip this step if you are already using Preline UI as a package.

  1. Install the plugin

    Install @preline/combobox via npm

    Terminal 
                              
                            npm i @preline/combobox

  2. Add the plugin CSS

    Use @source to register the plugin's JavaScript path for Tailwind CSS scanning, then @import the plugin's CSS files into your Tailwind CSS file.

    main.css 
                              
                            @import "tailwindcss";
                            
                            /* @preline/combobox */
                            /* [!code highlight:3] */
                            @source "../node_modules/@preline/combobox/*.js";
                            @import "./node_modules/@preline/combobox/variants.css";
                            @import "./node_modules/@preline/combobox/theme.css";

  3. Add the plugin JavaScript

    Include the JavaScript <script> that powers the interactive elements near the end of your </body> tag:

    HTML

    Additional Initialization Options

    Use the non-auto entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

    HTML (non-auto)

    Via bundler

    When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module.

    JavaScript (auto) 
                              
                            import "@preline/combobox";
    JavaScript (non-auto) 
                              
                            import HSCombobox from "@preline/combobox/non-auto";
                            
                            HSCombobox.autoInit();
                            
                            // Or initialize a specific element manually
                            const el = document.querySelector("#combobox");
                            if (el) new HSCombobox(el);

Example

Autosuggestion of countries from the list.

Basic usage

Prefer to create your own style? Here is a completely unstylized example.

HTML 
                      
                        <div class="inline-flex relative" data-hs-combo-box>
                          <div class="relative">
                            <input type="text" role="combobox" aria-expanded="false" value="" data-hs-combo-box-input />
                          </div>
                          <div class="absolute z-50" style="display: none;" data-hs-combo-box-output>
                            <div class="cursor-pointer" tabindex="0" data-hs-combo-box-output-item>
                              <span data-hs-combo-box-search-text="1" data-hs-combo-box-value>1</span>
                            </div>
                            <div class="cursor-pointer" tabindex="1" data-hs-combo-box-output-item>
                              <span data-hs-combo-box-search-text="2" data-hs-combo-box-value>2</span>
                            </div>
                          </div>
                        </div>

JavaScript behavior

Data Options

Name Description Options Default value
data-hs-combo-box Activate a ComboBox by specifying on an element. Should be added to the container. — —
:gap Determines the indent from the input field to the dropdown list. number 5
:viewport Determines which element will be the parent when calculating the position of the dropdown list. By default it is calculated relative to the document. string | HTMLElement null
:minSearchLength Specifies the minimum number of characters that must be entered before the search function becomes active. number 0
:apiUrl Specifies the API address. string | null null
:apiDataPart Determines which part of the returned data will be taken as the main data array. f this parameter is empty, then the root is taken as a basis. string | null null
:apiQuery Defines request parameters, such as limit. string | null null
:apiSearchQuery Defines the name of the search parameter. string | null null
:apiHeaders Defines request headers. string | null null
:apiSearchPath A string that specifies the endpoint path for the API request, excluding the base URL. For example, if the full API URL is https://some-api.com/part/of/the/url, apiSearchPath should be set to part/of/the/url.
Note: The parameters apiSearchPath and apiSearchDefaultPath are mutually exclusive with apiSearchQuery. Only one of these options should be used in a request to define the API endpoint path. 		string | null null
:apiSearchDefaultPath A string that defines the default API endpoint path to be used when the input field is empty or an empty request is sent. This path provides a fallback for requests without specific search terms. For example, if the full API URL is https://some-api.com/countries/all, set apiSearchDefaultPath to countries/all.
Note: The parameters apiSearchPath and apiSearchDefaultPath are mutually exclusive with apiSearchQuery. Only one of these options should be used in a request to define the API endpoint path. 		string | null null
:outputItemTemplate Defines a template for a single item in a dropdown list. string | null 
<div class="cursor-pointer py-2 px-4 w-full text-sm text-stone-800 hover:bg-stone-100 rounded-lg focus:outline-hidden focus:bg-stone-100 dark:bg-neutral-900 dark:hover:bg-neutral-800 dark:text-neutral-200 dark:focus:bg-neutral-800" data-hs-combo-box-output-item>
  <div class="flex justify-between items-center w-full">
    <span data-hs-combo-box-search-text></span>
    <span class="hidden hs-combo-box-selected:block">
      <svg class="shrink-0 size-3.5 text-blue-600 dark:text-blue-500" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
        <polyline points="20 6 9 17 4 12"></polyline>
      </svg>
    </span>
  </div>
</div>
:outputEmptyTemplate Defines a template for an empty placeholder. string | null 
<div class="py-2 px-4 w-full text-sm text-stone-800 rounded-lg dark:bg-neutral-900 dark:text-neutral-200">Nothing found...</div>
:outputLoaderTemplate Defines a template for the loader when loading data. string | null 
<div> class="flex justify-center items-center py-2 px-4 text-sm text-stone-800 rounded-lg bg-white dark:bg-neutral-900 dark:text-neutral-200">
  <div class="animate-spin inline-block size-6 border-3 border-current border-t-transparent text-blue-600 rounded-full dark:text-blue-500" role="status" aria-label="loading">
    <span class="sr-only">Loading...</span>
  </div>
</div>
:preventAutoPosition If true, it disables dropdown auto-positioning. boolean false
:preventClientFiltering If true, it disables client-side filtering. boolean true (if :apiSearchQuery is not empty)
:keepOriginalOrder If true, it keeps the original order of items. boolean false
:preserveSelectionOnEmpty If true, it preserves the selected value when the input is empty. boolean true
data-hs-combo-box-input Determines which element (input) inside the initialized container will be responsible for entering data. — —
data-hs-combo-box-output Determines which element inside the initialized container will be responsible for data output. — —
data-hs-combo-box-toggle Defines an element inside the initialized container that will be responsible for hiding/showing the dropdown list. — —
data-hs-combo-box-close Defines an element inside the initialized container that will be responsible for hiding the dropdown list. — —
data-hs-combo-box-open Defines an element inside the initialized container that will be responsible for showing the dropdown list. — —
data-hs-combo-box-output-item Defines an element inside the initialized container that will be responsible for displaying each individual data element. — —
> data-hs-combo-box-search-text Defines the element within which text will be searched. — —
> data-hs-combo-box-value Defines an element whose text will be set as a value when selected. — —
> data-hs-combo-box-output-item-field Defines a data field that will be taken to fill the element with text. string | string[] —
> data-hs-combo-box-output-item-attr Defines the attributes that will be filled with the corresponding data. For example, the src attribute of an image. — —
:valueFrom Defines the name of the field from which data will be taken. string —
:attr Defines the name of the attribute where the data will be supplied. string —

Tailwind Modifiers

Name Description
hs-combo-box-active:* A modifier that allows you to set Tailwind classes when SearchBox has been opened.
hs-combo-box-has-value:* A modifier that allows you to set Tailwind classes when SearchBox's input has value.
hs-combo-box-selected:* A modifier that allows you to set Tailwind classes when data-hs-combo-box-output-item has been selected.
hs-combo-box-tab-active:* A modifier that allows you to set Tailwind classes to the active group item (tab) when groupingType is tabs.

Methods

The HSCombobox object is contained within the global window object

Method Description
Public methods
getCurrentData() Returns the data of the selected element as an object. This data must first be assigned as a value to the data parameter data-hs-combo-box-item-stored-data, when standard rendering. And when rendering via the API, the data is automatically substituted into the data attribute (no need to do it yourself).
open() Open autosuggestion list.
close() Close autosuggestion list.
recalculateDirection() Forced recalculation of autosuggestion list positions.
destroy() Destroys the instance, removes generated markup (if any), removes added classes and attributes.
Static methods
HSCombobox.getInstance(target, isInstance) Returns the element associated to the target.
  • target should be a Node or string (valid selector)
  • isInstance boolean. Returns the instance instead of Node if true
HSCombobox.autoInit() Reinitializes all ComboBoxes on the page.
HSCombobox.close(target) Closes the target ComboBox.
  • target should be a Node or string (valid selector)
HSCombobox.closeCurrentlyOpened() Closes an already open ComboBox.

Open item (public method).

JavaScript 
                      
                        const comboBox = new HSComboBox(document.querySelector('#combo-box'));
                        const openBtn = document.querySelector('#open-btn');

                        openBtn.addEventListener('click', () => {
                          comboBox.open();
                        });

Open item (mixed).

JavaScript 
                      
                        const { element } = HSComboBox.getInstance('#combo-box', true);
                        const openBtn = document.querySelector('#open-btn');

                        openBtn.addEventListener('click', () => {
                          element.open();
                        });

Ready to use Components

Looking for prebuilt UI components based on the Tailwind CSS? Preline UI packs hundreds of component examples for all your website needs.

ComboBox (Autocomplete)

Explore ready-to-use Tailwind CSS examples built with Preline UI.

View ComboBox (Autocomplete) examples

ComboBox (Autocomplete)

© 2026 Preline Labs.