@cas-smartdesign/combo-box

A combo-box element with the look and feel of the SmartDesign inputs & list item layouts. It extends the lit-input, therefore the regular API of that element (such as configuring a label) should work here as well, except the value. As it is possible to select an item in the combo-box, the regular string based value may not be enough. Instead comboBoxValue property provides an extended information about the current selection.

Attributes

(in addition to lit-input)

• opened boolean (default=false)
  • Defines whether if the overlay is currently opened.
• item-height number (default=50)
  • Defines the height of the items.
• allow-custom-value boolean (default=false)
  • User may able to add custom value if it is set. Note that if the current value is such a custom one, then it's type is string.
• trigger-only boolean (default=false)
  • Defines if the element after a selection event may clear its value.
• null-setting-disallowed boolean (default=false)
  • Defines if using empty value is allowed via a clear button or just simply removing the text.
• display-value-path string (default=caption)
  • The currently selected item's property to show in the input.
• filter-property string (default=null)
  • Used for in memory filtering if set. The property of the item which is checked against the filter text. It is preferred to inMemoryFilter.
• has-value boolean (default=false)
  • Present if the input field has any text in it.
• show-icon boolean (default=false)
  • Defines if the currently icon of the selected or active item is shown as a prefix element.

Properties

(in addition to lit-input)

• itemHeight, opened, allowCustomValue, nullSettingDisallowed, displayValuePath, filterProperty, triggerOnly
  • Reflects the corresponding attribute.
• itemGenerator ItemGenerator
  • A function that renders the list items. Delegated to the list used in the dropdown. The default value is the one from the @cas-smartdesign/list-item.
• items Array (default=empty)
  • The data for the list items.
  • Should be pre-filtered only if lazy loading is used. For details, see the corresponding section below.
• inMemoryFilter Function (filterText, item) => boolean
  • Used for in memory filtering. The default value searches in caption & description properties.
• filterText string (default=null)
  • The currently used text with which the items are filtered.
• finalSizeIsKnown boolean (default=false)
  • Delegated to DataProvider used for the dropdown list.
• comboBoxValue ComboBoxValue (default=null)
  • The index of the currently selected item, and the item itself. Note that if the value is a "custom value" (see allowCustomValue) then this is only a string with the value in it without the index.
  • The value property inherited from the lit-input reflects the value used in the input field. This is also available through the displayValue property.
• minimumOverlayWidth number (default=250) in pixels
  • It is applied to the overlay's style.
  • There is also a maximum boundary for the overlay, which is 50vw by default, but both can be overridden by regular CSS rules.
  • Regardless of these values, the overlay cannot be smaller than the corresponding input field.

Custom events

• selection-change
  • Sent when the value (selection) of the combobox changes.
• filter-change
  • Sent when the value of the input is changed by typing and contains the value of it (this is used as a filter text).

Lazy loading

It is possible to fetch the suggestions from the server lazily. It means that if the combo-box is configured via the configureLazyLoad, then the included list in the dropdown will use the given onDataRequest callback. If the lazy mode is activated then inMemory filtering is disabled, but the mentioned data request is also called whenever the filter text changes. A loading attribute is added while a pending data request is present to be able to show a loading indicator for example. See the doc.ts for some comprehensive examples.