• advanced forms
  • Combo Box

advanced forms

Tailwind CSS Combo Box

The ComboBox JavaScript plugin improves user experience by dynamically suggesting options as users type into an input field.

Require FlyonUI JS
Class Name
Type
Description
dropdown-itemModifierStyles applied to individual dropdown items.
combo-box-active:{tw-utility-class}VariantModifies tailwind classes when the combo box is active.
combo-box-selected:{tw-utility-class}VariantModifies tailwind classes when the combo box is selected.
combo-box-tab-active:{tw-utility-class}VariantModifies tailwind classes when the combo box tab is active.
combo-box-has-value:{tw-utility-class}VariantA modifier that enables you to apply Tailwind classes when the SearchBox’s input field contains a value.

Basic example

HTML example

The code snippet outlines a ComboBox with specific data attributes to manage its behavior. The outer <div> with data-combo-box signifies that this section is the main ComboBox component. Within it, an <input> field with data-combo-box-input allows users to type text to get suggestions.

An accompanying icon element with data-combo-box-toggle acts as a button to open or close the dropdown menu, indicating it has a dropdown function. The dropdown menu itself is an <div> with data-combo-box-output, which contains several suggestion items. These individual suggestion items are <div> elements with data-combo-box-output-item. Each item has a data-combo-box-search-text attribute that holds the text displayed for that option in the dropdown.

Below example shows basic use of combo-box.

JSON example

A JSON-based ComboBox example.

A ComboBox, a dropdown component allowing users to type for suggestions, is being set up. The root div includes an attribute apiUrl, indicating the ComboBox where to retrieve data.

In this instance, it’s set to https://www.freetestapi.com/api/v1/countries, used to obtain a list of countries.

Another attribute, outputItemTemplate, defines the layout for each item within the dropdown menu. It comprises HTML structure incorporating data-combo-box-output-item to represent individual dropdown items. Each item includes a section for the name (utilizing data-combo-box-output-item-field="name") and a span for a checkmark icon, visible upon item selection.

JSON Example (based on API pathes)

A JSON-configured ComboBox that retrieves options from an API. apiSearchPath specifies the API endpoint for searching items. apiSearchDefaultPath sets the default API endpoint to load all items initially.

Option usage

Search and limit parameters

:apiSearchQuery serves as a property or parameter containing the key name utilized for searching within a dataset when making API calls. Usually, it’s combined with user-entered text to generate a query string, which is then appended to the base API endpoint (apiUrl), resulting in the complete URL required to fetch the data.

:apiQuery represents additional query parameters for the API request, such as limit. :outputEmptyTemplate enables you to specify the content to display when no matching options are available.

The following example demonstrates the usage of search and limit parameters in a combo box.

Minimum search Length

Set "minSearchLength": 2 to define the minimum number of characters required before initiating a search.

Open on focus

When isOpenOnFocus is enabled, the dropdown menu will automatically appear upon focusing on the input field.

Alternatively, users have the option to utilize the data-combo-box-toggle attribute, designating an element within the ComboBox responsible for toggling the visibility of the dropdown list.

Close Button

A basic usage of ComboBox with close button.

SearchBox

Html example

Combo box html example with dropdown and modal.

Dropdown

Below is an example showcasing the utilization of the SearchBox within a dropdown, employing data attributes in HTML. Furthermore, the example illustrates how to create groups.

Modal

A combo box displaying HTML content within a modal.

Json example

Combo box example using JSON data displayed within a dropdown and a modal.

Dropdown

Utilizing a JSON example in a dropdown, use option :apiGroupField to select a heading. Positions are categorized as headings in this scenario.

Modal

Combo box with json data show in modal.

Json with tab filter

Combo box example demonstrating tab filtering functionality, incorporating both dropdown and modal components.

Dropdown

Experience tab filtering within a dropdown. Set :groupingType to tabs, utilize :groupingTitleTemplate to style the filtering tabs, and :tabsWrapperTemplate to style the tab wrapper.

Modal

In this example, a modal popup is employed to provide a user-friendly tab filtering experience.

Illustrations

Destroy/Reinitialize

The destroy method is provided to facilitate the destruction of a toggle count.

Accessibility notes

Keyboard interactions

COMMAND
DESCRIPTION
EnterActivates the selected tab.
A-Z a-z
Focuses first item that matches keyboard input.
Home End
Focuses first/last non-disabled item.
EscCloses any open Menus.
Focuses previous/next non-disabled item.

JavaScript behavior

Options

PARAMETERS
DESCRIPTION
OPTIONS
DEFAULT VALUE
General Options
data-combo-boxActivates a ComboBox on a specific element.——
:gapDefines the gap between the input field and the dropdown list.number6
:viewportSpecifies the parent element for calculating dropdown list position, by default relative to the document.string, HTMLElement—
:preventVisibilityIf true, prevents visibility changes in the ComboBox.booleanfalse
:preventSelectionIf true, prevents item selection in the dropdown list.booleanfalse
:isOpenOnFocusIf true, the dropdown list opens when the field is focused.booleanfalse
:groupingTypeType of grouping used in the dropdown.default, tags—
:groupingTitleTemplateTemplate for the title in grouped ComboBox.One line HTML markup—
:preventAutoPositionIf true, it disables dropdown auto-positioning.booleanfalse
:preventClientFilteringIf true, it disables client-side filtering.booleantrue (if :apiSearchQuery is not empty)
:tabsWrapperTemplateTemplate for the tabs wrapper in the ComboBox.One line HTML markup<div class="overflow-x-auto p-4"></div>
:keepOriginalOrderIf true, it keeps the original order of items.booleanfalse
:preserveSelectionOnEmptyIf true, it preserves the selected value when the input is empty.booleantrue
:minSearchLengthSets the minimum number of characters required to activate the search functionality.number0
API Options
:apiUrlThe URL endpoint for fetching data via API.string, null—
:apiDataPartSpecifies the part of the returned data to use as the primary data array.string, null—
:apiQueryParameters for API requests, like limiting results.string, null—
:apiSearchQueryParameter name used for search queries.string, null—
:apiHeadersHeaders to include in API requests.object{}
:apiGroupFieldField in the API response used for data grouping.string, null—
:apiSearchPathA 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—
:apiSearchDefaultPathA 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—
Template Options
:outputItemTemplateTemplate for individual items in the dropdown list.string, null<div class="dropdown-item combo-box-selected:dropdown-active" data-combo-box-output-item> ... </div>
:outputEmptyTemplateTemplate for when no data is found in the dropdown.string, nullNothing found...
:outputLoaderTemplateTemplate for the loader when fetching data.string, null<span class="loading loading-spinner text-primary"></span>
:searchWrapperTemplateTemplate for the search field wrapper.string, null<div></div>
Input & Output Options
data-combo-box-inputIdentifies the element responsible for data entry in the ComboBox.——
data-combo-box-outputIdentifies the element that outputs data from the ComboBox.——
data-combo-box-toggleElement that toggles the dropdown list.——
data-combo-box-openElement that open the dropdown list.——
data-combo-box-closeElement that close the dropdown list.——
data-combo-box-output-itemDefines an element within the initialized container that will handle the display of each individual data item.——
> data-combo-box-search-textDefines the element within which text will be searched.——
> data-combo-box-valueDefines an element whose text will be set as a value when selected.——
> data-combo-box-output-item-fieldDefines a data field that will be taken to fill the element with text.——
> data-combo-box-output-item-attrDefines the attributes that will be filled with the corresponding data. For example, the src attribute of an image.——
:valueFromField name from which data will be taken.string—
:attrAttribute name where data will be supplied.string—

Methods

The HSCombobox object is contained within the global window object.

METHOD
DESCRIPTION
PUBLIC METHODS
getCurrentDataReturns the data of the selected element as an object. This data must first be assigned as a value to the data parameter data-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()Opens the autosuggestion list.
close()Closes the autosuggestion list.
recalculateDirection()Forces recalculation of the autosuggestion list’s 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 with the target.
  • The target can be a Node or a valid CSS selector.
  • isInstance (boolean) - returns the instance instead of the Node if true.
HSCombobox.autoInit()Reinitializes all ComboBoxes on the page.
HSCombobox.close(target)
Closes the target ComboBox.
  • The target should be a Node or a valid CSS selector.
HSCombobox.closeCurrentlyOpened()Closes the currently opened ComboBox.

Method usage

Below, is the demonstration on how to use the methods. To test other methods, copy the following methods into your console and click the button.

Open item (public method).

// This method is used in above example.
const comboBox = new HSComboBox(document.querySelector('#combo-box-method'));
const openBtn = document.querySelector('#open-btn')

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

Open item (mixed).

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

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

Destroy instance.

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

destroyBtn.addEventListener('click', () => {
  element.destroy();
});

Events

METHOD
DESCRIPTION
RETURNING VALUE
on:selectCalled when any select is changed.Current value

Event usage

Display a console log message when an option is selected.

When select changes event example.

const {element} = HSComboBox.getInstance('#event-select', true);

element.on('select', (value) => {console.log("element.value")});