A combobox is a complex element, which can be considered as a combination of two elements - a dropdown list and a text input. The text input is used for quick search and filtering of the predefined options from the dropdown list.
Use a combobox when you need to have a list of options with search and filtering capabilities. This is a common pattern in web UI and is similar to the native datalist. In contrast to the datalist, a combobox features multiple selection and possibility to build richer UI for each option in the list, with images and styling. Adding free text input that is not part of the predefined list is not supported in the combobox.
The combobox can be configured in several different ways, depending on how the options are loaded, whether a single value or multiple values can be selected.
This basic type of combobox features declarative list of options. It's suitable for smaller, static lists.
This type is dynamic and is generated from an array of data. The user supplies a template which tells how any option will be displayed in the list. When an option is selected, its display name gets populated in the search box.
The multi select combobox is similar to the single select one, as it is data driven and allows for detailed configuration of the option display. After selection is made, a pill is created that corresponds to the selected item. Multi selection is achieved by subsequent selection from the drop down list, adding pills to the pills list.
The asynchronous scenario allows for lazy loading of the pre-selected options. There is a "loading" spinner and message that's displayed before the options load is complete.
As part of the forms elements collection, the Combobox has a label, that can be vertically or horizontally aligned to it. It also has a condensed mode, that occupies less space. It has helper text and error/success message area. The component itself has a text input where the users enter the search text and a dropdown area, with a list of predefined options which can be styled by the user. The multi select version of the combobox has a list of pills that is situated before the text input. These pills all feature a delete button, and can also be styled, similarly to the options.
The current selection is pre-filled in the text input box. Changing the input text does not change the selection until an option is selected from the drop down list. Selection can only be changed, not deleted.
Current selection is displayed as a list of pills before the input box. New pills can be added from the drop down list. Pills can be deleted by clicking the "X" icon on each pill. Also, pressing Backspace key in an empty input box will select the last pill in the list.
The drop down with the pre-selected options can be opened either by clicking on the down caret icon at the end of the input text box, or by typing into the text box.
Options can be mouse clicked to be selected. Also keyboard navigation with the arrow keys and selection with Enter key is available. Selected option/s are highlighted in the list.
Typing in the input text box will filter the drop down list of predefined options. This works in all cases with the exception of the basic, declarative list with static options, as they don't use the smart options iterator which is used in the dynamic scenarios.
A basic static combobox can be created by directly nesting
clr-option components in the
A single selection combobox is taking advantage of the
*clrOptionItems smart iterator to manage its inventory of pre-selected options. It is similar to
*NgFor as syntax.
field:'name' designates which field of the underlying data object should be used as display name. The html nested inside the
clr-option node will be used as template for the option design. It can include images, text, html code.
The multi selection mode is triggered with a
clrMulti="true" attribute on the
In regard to option management, the multi select combobox works the same as the single select one. It uses
*clrOptionItems smart iterator and a template inside
clr-option node for option styling.
Pill styling is defined inside
*clrOptionSelected structural directive, as seen in the example.
Using the combobox asynchronously requires to manually bind several event handlers on the
(clrOpenChange)="$event ? fetchStates() : null" need to be bound to your method that fetches the backend data ("fetchStates()" in this example). Then
[clrLoading]="loading", which triggers the display of the "loading" indicator, should be bound to a property that is active while your data fetching called is in progress.