KTUI
Docs
Advanced Select

Advanced Select

KTSelect is a feature-rich, customizable dropdown component built with modern web standards. It offers single/multiple selection, search, and rich icon support with various styling options.

Examples

Basic Usage

A simple dropdown select component for single option selection.

Avatar

A select component with avatar images template for each option.

Country

A select component with country flags template for each option.

Description

A select component with description template for each option.

Disabled Options

A select component with disabled options.

Disable Select

A select component with disabled state.

Icon Multiple

A select component with multiple icon template for each option.

Icon

A select component with icon template for each option.

Max Selection

A select component with max selection.

Modal

A select component with modal.

Multiple

A select component with multiple selection.

Placeholder

A select component with placeholder.

Search

A select component with search.

Sizes

A select component with sizes.

Component API

Options

These data attributes allow you to configure the select component during initialization.

OptionTypeDefaultDescription
data-kt-selectbooleantrueInitialize KTSelect on this element.
data-kt-select-placeholderstring""Custom placeholder text when no option is selected
data-kt-select-multiplebooleanfalseEnable multiple selection mode
data-kt-select-max-selectionsnumbernullMaximum number of selectable options in multiple mode, null for unlimited
data-kt-select-disabledbooleanfalseDisable the entire select component
data-kt-select-enable-searchbooleanfalseEnable search functionality within the dropdown
data-kt-select-search-placeholderstring"Search..."Placeholder text for the search input
data-kt-select-search-emptystring"No results"Text to display when no search results are found
data-kt-select-dropdown-zindexnumber105Z-index of the dropdown menu
data-kt-select-dropdown-containerstringnullContainer element for the dropdown menu
data-kt-select-dropdown-placementstringnullPlacement of the dropdown menu
data-kt-select-configstringnullJSON configuration object for advanced options (see below)

Template Config

All advanced options, including templates, classes, and more, are passed via the data-kt-select-config attribute as a flat JSON string. Config keys include:

OptionTypeDefaultDescription
optionTemplatestringnullCustom template for dropdown options.
displayTemplatestringnullCustom template for the selected value display.
dropdownTemplatestringnullCustom template for the dropdown container.
placeholderTemplatestringnullCustom template for the placeholder.
searchEmptyTemplatestringnullTemplate shown when search returns no results.
optionsClassstringnullAdditional classes for the dropdown options container.
optionClassstringnullAdditional classes for each option.
displayClassstringnullAdditional classes for the display element.
placeholderClassstringnullAdditional classes for the placeholder element.
displaySeparatorstring", "Separator string for multiple selected values.
placeholderstring""Placeholder text when no option is selected.

Example:

<select
  data-kt-select
  data-kt-select-placeholder="Select an option"
  data-kt-select-config='{
    "optionTemplate": "<div class=\"custom-option\">{{text}}</div>",
    "displayTemplate": "<div>{{text}}</div>",
    "dropdownTemplate": "<div class=\"custom-dropdown\">{{optionsHtml}}</div>",
    "placeholderTemplate": "<span class=\"custom-placeholder\">{{placeholder}}</span>",
    "searchEmptyTemplate": "<div class=\"no-results\">No results found</div>",
    "optionsClass": "kt-scrollable overflow-auto max-h-[250px]",
    "optionClass": "kt-select-option",
    "displayClass": "kt-select-display",
    "placeholderClass": "kt-select-placeholder",
    "displaySeparator": ", ",
    "placeholder": "Select a country..."
  }'
>
  <option value="1">Option 1</option>
  <option value="2">Option 2</option>
</select>

Option Data

Each <option> can include a data-kt-select-option attribute with a JSON object. Any key in this object is available as a template variable for that option.

Example:

<select
  data-kt-select
  data-kt-select-config='{
    "optionTemplate": "<div class=\"custom-option flex items-center gap-2\">{{icon}} <span>{{text}}</span><span class=\"ml-2 text-xs text-muted-foreground\">{{description}}</span></div>",
  }'
>
  <option
    value="1"
    data-kt-select-option='{
      "icon": "<img src=\"/avatar.jpg\" class=\"w-8 h-8 rounded-full\" />",
      "description": "Administrator account"
    }'
  >
    John Doe
  </option>
</select>

Events

All events are dispatched on the <select> element and use the unprefixed names:

EventPayload (event.detail.payload)Description
change{ value: string, selected: boolean, selectedOptions: string[] }Triggered when an option's selection state changes.
shownullTriggered when the select dropdown is opened.
closenullTriggered when the select dropdown is closed.

Listening to Events:

All custom events are dispatched on the <select> element and use the event name without any prefix. Example:

selectElement.addEventListener('change', (event) => {
  const { value, selected, selectedOptions } = event.detail.payload;
  // handle change
});
 
selectElement.addEventListener('show', () => {
  // handle dropdown open
});
 
selectElement.addEventListener('close', () => {
  // handle dropdown close
});
PreviouseScrolltoNextSeparator