Tailwind CSS Combobox Plugin API

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

Installation

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

Terminal

                        
                          npm i @preline/combobox

Example

Autosuggestion of countries from the list.

Basic usage

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

                      
                        <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">1</span>
                            </div>
                            <div class="cursor-pointer" tabindex="1" data-hs-combo-box-output-item>
                              <span data-hs-combo-box-search-text="2">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-gray-800 hover:bg-gray-100 rounded-lg focus:outline-hidden focus:bg-gray-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-gray-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-gray-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).

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

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

Open item (mixed).

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

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

Demo examples

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

Check out Preline UI Components

Tailwind CSS Combobox Plugin API

On this page