Displays a list of options for the user to pick from—triggered by a button.
The custom select component is a web component built from scratch to enhance the native <select> tag. To get started, simply use the <uk-select> markup in your HTML code with one <select data-fn="data-source" hidden></select> tag as options reference.
There are several ways to capture values from the <uk-select> component. The simplest approach is to add a name attribute to the component. When you do this, a hidden input field with the specified name will be automatically generated, allowing you to easily capture the selected value on your server.
Note If you don’t specify a value attribute for an <option> tag, it will default to using its text content as the value instead.
Because the <uk-select> component uses the Drop component under the hood, we can leverage its positioning capabilities and position our dropdown anywhere we want. To position it, just use the drop attribute with your drop options.
There are several size modifiers available. Just add one of the following classes to make the fake input smaller or larger.
| Class | Description |
|---|---|
.uk-form-xsmall | Applies extra small size. |
.uk-form-small | Applies small size. |
.uk-form-medium | Applies medium size. |
.uk-form-large | Applies large size. |
To add a header to your custom select component, use the <optgroup> tag, which will be automatically converted into a dropdown header, providing a seamless developer experience.
To enable the selection of multiple values, simply add the multiple attribute to the <uk-select> element. This will allow users to choose multiple options from the dropdown list.
Note When utilizing the
multiple attribute, note that it will automatically append [] to the name of
your input. This is particularly useful when your server expects multiple
values, even if the user selects only one option. This ensures that your
server-side logic can properly handle the input, regardless of the number of
values selected.
There are two ways to prepopulate values from the <uk-select> component. The simplest approach is to add a selected attribute to one or more of your <option> tags.
In multiple mode:
name[] for form submissionaria-multiselectable="true"Alternatively, if setting selected on individual <option> elements is not feasible, you can use the value attribute on the <uk-select> tag to prepopulate it with default values. This attribute accepts a comma-separated list of values, allowing you to set multiple defaults, such as value="Mercedes-Benz,Bentley,Porsche,Lamborghini".
Note When both value and
selected are used, the value attribute takes precedence. Therefore, it’s
recommended to use one method or the other to avoid conflicts.
Similar to the native <select> tag, you can disable specific options in the custom select component by adding the disabled attribute to one or more of your <option> or <optgroup> tags. This allows you to prevent users from selecting certain options.
By default, the component is not reactive. This is a deliberate design choice, as using MutationObserver can be computationally expensive. As a result, changes to the referenced <select data-fn="data-source" hidden> element will not trigger an update.
To enable reactivity, simply add the data-reactive attribute to the <select data-fn="data-source" hidden> tag. This will use MutationObserver under the hood to monitor the element for changes.
This feature is particularly useful when using libraries like HTMX, where you may need to dynamically update the options in the <select data-fn="data-source" hidden> element based on user interactions, such as searching for data or fetching new options from the server.
To add a search box, simply add the searchable attribute. This will add an input field within the dropdown menu, enabling users to search for specific options. This feature is particularly useful when dealing with extensive lists, such as selecting a country from a long list of options.
Search features:
uk-select:search event on search term changeSometimes, there are items that have related keywords that may be slightly off or awkward when included as anchor tags. For these use cases, we can leverage the data-keywords attribute.
For example, if we have a “Form” link but also want it to appear when users search for terms like “checkbox,” “input,” “toggle switch,” etc., we can simply add a comma-separated list of terms like this: data-keywords="apple, mango, lemon".
To prevent user input, add the disabled attribute to the <uk-select> element. This will disable the custom select, making it impossible for users to enter or modify its value.
This component allows you to customize icons through the template system:
To add icon to options, just add data-icon attribute with the name of the icon to your <option> tags.
The Select component supports internationalization through multiple methods with the following priority order (highest to lowest):
i18n attribute or script tag)<script id="uk-i18n">)Place this in your document <head> or before any select components:
| Key | Default | Description |
|---|---|---|
search-placeholder | Search | Placeholder text for search input field |
selection-count | {n} options selected | Text shown when multiple options are selected (supports {n} placeholder) |
insert | Insert | Button text for inserting custom options |
list-label | Options | ARIA label for the listbox |
button-label | Select an option | ARIA label and default text for the select button |
The Select component supports custom CSS classes through the cls attribute. This allows you to style specific elements within the select without modifying the component’s internal structure.
Apply a class to the default element (button):
Target specific elements within the select:
| Target | Description |
|---|---|
host-inner | The main wrapper container for the entire component |
button | The clickable button that opens the dropdown |
button-text | The text span inside the button showing selected option(s) |
icon | The icon element inside the button (when icon attribute is set) |
dropdown | The dropdown container holding the list and search |
list | The listbox (ul) containing all options |
item | Individual list item (li) wrapper |
item-active | The active list item (li) |
item-disabled | Class for disabled list item (li) |
item-header | Group header for grouped options |
item-link | The clickable button/link inside each item |
item-wrapper | Wrapper for item content (icon + text) |
item-icon | Icon element for options with data-icon |
item-text | Text label for the option |
item-check | Checkmark indicator for selected options |
item-subtitle | Description/subtitle text for options with data-description |
search | Search input wrapper (when searchable is enabled) |
search-input | The actual search input field |
search-icon | Icon displayed in search input |
divider | Class for the divider element |
The Select component supports custom inline styles through the stl attribute. This allows you to apply specific CSS styles to individual elements within the select.
Apply styles to the default element (button):
Target specific elements with custom styles:
The stl attribute supports the same targets as the cls attribute. See the Available cls targets table above for a complete list of targetable elements.
To indicate an error state in the form, simply add the .uk-form-danger class to the cls attribute. This will apply a “danger” state to the component, providing visual feedback to the user.
When loading Web Components, a brief delay may cause a flash of unstyled content. To mitigate this issue, consider setting a predefined height on the parent element to prevent layout shift and ensure a smooth user experience.
The following attributes are available for this component:
| Name | Type | Default | Description |
|---|---|---|---|
drop | String | mode: click; animation: uk-animation-slide-top-small; | Dropdown positioning options (UIkit Drop configuration) |
searchable | Boolean | false | Enables search functionality to filter options |
insertable | Boolean | false | Allows inserting custom options (auto-enables searchable) |
send-headers | String | JSON object of HTTP headers for server validation requests | |
send-url | String | Server endpoint URL for validating inserted options | |
send-method | String | POST | HTTP method for server requests |
multiple | Boolean | false | Enables multi-select mode |
icon | String | Custom icon/text displayed in the button | |
name | String | Name attribute for hidden input(s), enabling form submission | |
disabled | Boolean | false | Disables the entire component, preventing user interaction |
required | Boolean | false | Marks the select as required for form validation |
placeholder | String | Custom placeholder text when no option is selected | |
value | String | Pre-selected value(s). Use comma-separated for multiple selections | |
cls | String | Custom CSS classes. Can be simple string or JSON object for targeting elements | |
stl | String | Custom inline styles. Can be simple string or JSON object for targeting elements | |
i18n | String | Internationalization strings as JSON object or via configuration script | |
force-prevent-rerender | Boolean | false | Prevents component rerendering (useful for HTMX or SPA scenarios) |
The Select component triggers the following events:
| Name | Description |
|---|---|
uk-select:input | Fired when the selected value(s) change. Event detail contains {value: string | string[]}. |
uk-select:search | Fired when the search term changes (when searchable is enabled). Event detail contains {value: string}. |