Select

Displays a list of options for the user to pick from—triggered by a button.

Table of contents

• Usage
• Capturing values
• Parent icon
• Options icon
• Position
• Size modifiers
• Adding header
• Selecting multiple values
• Prepopulating values
  • Manually setting value
• Disabling options
• Reactivity
• Searchable
  • Custom keywords
• Disable input
• Error state
• Preventing layout shift
• Internationalization
• Styling
• Available options
• Attributes
• Events

Usage

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 hidden></select> tag as options reference.

Capturing values

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.

Parent icon

To add a parent icon, just add an icon attribute to the <uk-select> component. If you want to customize the icon, just pass a string name of the icon.

Options icon

To add icon to options, just add data-icon attribute with the name of the icon to your <option> tags.

Position

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.

Size modifiers

There are several size modifiers available. Just add one of the following classes to make the fake input smaller or larger.

Adding header

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.

Selecting multiple values

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.

Prepopulating values

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.

Manually setting value

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.

Disabling options

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.

Reactivity

Experimental By default, the <uk-select> 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 hidden> element will not trigger an update.

To enable reactivity, simply add the reactive attribute to the <uk-select> component. This will use MutationObserver under the hood to monitor the <select hidden> 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 hidden> element based on user interactions, such as searching for data or fetching new options from the server.

Searchable

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.

Custom keywords

Sometimes, 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".

Disable input

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.

Error state

To indicate an error state in the form, simply add the .uk-form-destructive class to the cls-custom attribute. This will apply a “destructive” state to the component, providing visual feedback to the user.

Preventing layout shift

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.

Internationalization

Styling

The <uk-select> component is intentionally unstyled by default, allowing you to easily customize its appearance to fit your needs.

To add custom styles, use the cls-custom attribute. This attribute accepts two formats:

• A JSON-stringified object
• A valid key: value; foo: bar; format

If you pass only class names, they will be applied directly to the button inside the component.

Available options

Attributes

The following attributes are available for this component:

Events

The custom select component triggers the following events on elements with this component attached: