1. Plugins
  2. Combobox

Plugins

Tailwind CSS ComboBox

Dynamic suggestions as users type in an input field.

ComboBox

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.

                      
                        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" 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>

Options

Name Description Options Default value
data-hs-combo-box Activate a ComboBox by specifying on an element. — —
: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
: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
: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-none 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="flex-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-[3px] 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>
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-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 —
> 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 —

Methods

The HSCombobox object is contained within the global window object

Method Description
Public methods
open() Open autosuggestion list.
close() Close autosuggestion list.
recalculateDirection() Forced recalculation of autosuggestion list positions.
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 } = HSCopyMarkup.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.

Image Description
Check out Preline UI Dismiss