LookupField

import {LookupField} from 'cx/widgets';

The LookupField control offers selection from a list of available options. It is very similar to the well-known HTML select element, however it offers a few additional features such as:

Searching the list
Querying remote data
User-friendly multiple selection mode

Most of these features were implemented following the excellent select2 jQuery plugin.

Select
MultiSelect
Records

Remote Data
Local Filter
Icon

Sometimes, available options are known or immediately available. In that case, it's enough to pass options to the control and search is done in the browser. This mode is similar to the functionality of the native select HTML element, because available options appear instantly. When there are just a few options, the search field is automatically hidden.

Another, very common use case is when available options need to be fetched from the server. To achieve that, it's required to implement an onQuery callback for the widget. The result of the callback should be a list of options or a Promise which resolves the list.

It's important to remember how to properly bind data to the LookupField widget. If multiple option is not specified (single selection mode), then it's required to bind value and text properties.

In multiple selection mode, it's necessary to bind the records or values property. The records property will hold a list of the selected values. By default, only id and text properties are copied from the option to the selection; however, it's possible to provide a list of bindings which describes the mapping between options and value fields.

The following table shows valid property combinations in different modes.

Selection/Mode	Local (options)	Remote (onQuery)
Single	`value` and/or `text`	`value` and `text`
Multiple	`values` and/or `records`	`records`

Controller LookupField

<div class="widgets" controller={PageController}>
    <div layout={LabelsLeftLayout}>
        <LookupField
            label="Select"
            value-bind="$page.s5.id"
            text-bind="$page.s5.text"
            options-bind="$page.options5"
            autoFocus
        />
        <LookupField
            label="MultiSelect"
            records-bind="$page.s10"
            options-bind="$page.options10"
            multiple/>
        <LookupField
            label="Records"
            values-bind="$page.s10ids"
            options-bind="$page.options10"
            multiple/>
    </div>
    <div layout={LabelsLeftLayout}>
        <LookupField
            label="Remote Data"
            records-bind="$page.selectedCities"
            onQuery="query"
            minQueryLength={2}
            multiple/>
        <LookupField
            label="Local Filter"
            records-bind="$page.selectedCities2"
            onQuery="query"
            fetchAll
            cacheAll
            multiple
            icon="filter"
            closeOnSelect={false} />
        <LookupField
            label="Icon"
            value-bind="$page.s5.id"
            text-bind="$page.s5.text"
            icon={{
                name: "pencil",
                onClick: (e) => {
                    e.stopPropagation();
                    MsgBox.alert("Icon clicked.");
                },
                tooltip: "This tooltip is displayed only over the icon."
            }}
            options-bind="$page.options5"/>
    </div>
</div>

Copied!Cx Fiddle

Examples:

Custom bindings - for passing additional options to the selection
Infinite lists - for lookups with large number of options
Options filter - for lookups supporting options filtering
Options grouping - for lookups with options grouping

Configuration

Property	Description	Type
multiple	Defaults to `false`. Set to `true` to enable multiple selection.	boolean
optionIdField	Name of the field which holds the id of the option. Default value is `id`.	string
optionTextField	Name of the field which holds the display text of the option. Default value is `text`.	string
options	A list of available options.	array
records	A list of selected records. Used only if `multiple` is set to `true`.	array
text	Text associated with the selection. Used only if `multiple` is set to `false`.	string
value	Selected value. Used only if `multiple` is set to `false`.	number/string
valueIdField	Available only in `multiple` selection mode and without custom `bindings`. Name of the field to store id of the selected value. Default value is `id`.	string
valueTextField	Available only in `multiple` selection mode. Name of the field to store display text of the selected value. Default value is `text`.	string
values	A list of selected ids. Used only if `multiple` is set to `true`.	array
alwaysShowClear	Set to `true` to display the clear button even if `required` is set. Default is `false`.	boolean
autoFocus	Set to `true` to automatically focus the field, after it renders for the first time.	boolean
autoOpen	Set to `true` to auto open the drop-down. Commonly used in cell-editable grids.	boolean
baseClass	Base CSS class to be applied to the field. Defaults to `lookupfield`.	string
bindings	An array of mappings between options and value fields. Use this property to pass additional options to the selection. See example.	array
cacheAll	If this flag is set along with `fetchAll`, fetched options are cached for the lifetime of the widget. Otherwise, data is fetched whenever the dropdown is shown.	boolean
class className	Additional CSS classes to be applied to the element. If an object is provided, all keys with a "truthy" value will be added to the CSS class list.	string/object
closeOnSelect	Close the dropdown after selection. Default is `true`.	boolean
disabled	Defaults to `false`. Set to `true` to disable the field.	boolean
dropdownOptions	Additional configuration to be passed to the dropdown, such as `style`, `positioning`, etc.	config
emptyText	Text to be rendered in view mode when the field is empty.	string
emptyValue	Value to be written in the store when the field is empty. Default value is `null`.	any
enabled	The opposite of `disabled`.	boolean
error	Used for validation. If error evaluates to non-null, the field is marked in red.	string
fetchAll	If `true` `onQuery` will be called only once to fetch all options. After that options are filtered client-side.	boolean
filterParams	Parameters which will be passed to the onCreateFilter callback.	object
help	Additional content to be displayed next to the field. This is commonly used for presenting additional information or validation errors.	string/config
helpPlacement	Set to `material` to use custom help placement instruction. Used in Material theme to implement absolutely positioned validation messages.	string
helpSpacer	Indicates that `help` should be separated from the input with a whitespace. Default is `true`.	boolean
hideClear	Set to `true` to hide the clear button. It can be used interchangeably with the `showClear` property. No effect if `multiple` is used. Default value is `false`.	boolean
hideSearchField	Set to `true` to hide the search field.	boolean
icon	Name or configuration of the icon to be put on the left side of the input.	string/object
id	Id to be used on rendered input.	string
infinite	Set to `true` to enable loading of additional lookup options through scrolling.	boolean
inputAttrs	Additional attributes that should be rendered on the input element. E.g. `inputAttrs={{ autoComplete: "off" }}`.	object
inputClass	Additional CSS class applied to the input element. Used for setting visual elements, such as borders and backgrounds.	string/object
inputStyle	Style object applied to the input element. Used for setting visual elements, such as borders and backgrounds.	string/object
label	Field label. For advanced use cases, see Labels.	string/config
labelClass	Additional CSS class to be passed to the label object.	string
labelPlacement	Set to `material` to use custom label placement instruction. Used in Material theme to implement animated labels.	string
labelStyle	Additional CSS styles to be passed to the label object.	string/object
listOptions	Options that will be passed to the List widget inside the drop-down.	config
minOptionsForSearchField	Number of options required to show the search field. If there are only a few options, there is no need for search. Defaults to `7`.	number
minQueryLength	Number of characters required to start the search. Default `0`.	number
mod	Appearance modifier. For example, `mod="big"` will add the CSS class `.cxm-big` to the block element.	string/array
mode	Either `view` or `edit` (default). In view mode, the field is displayed as plain text.	string
onCreateVisibleOptionsFilter	Callback function used to create a filter. The function accepts `filterParams` as a first argument and it should return a predicate function used to filter the records. Callback is invoked on every `filterParams` change, if latter is specified.	function
onGetRecordDisplayText	Used in multiple selection lookups in combination with records, to construct the display text out of multiple fields or when additional formatting is needed.	function
outerLayout	Defines the outer layout which wraps the widget.	widget
pageSize	Number of additional items to be loaded in `infinite` mode. Default is 100.	number
placeholder	Default text displayed when the field is empty.	string
putInto contentFor	Used with outer layouts. Specifies the name of the content placeholder which should render the widget.	string
queryDelay	A delay in milliseconds between the moment the user stops typing and when tha query is made. Default value is `150`.	number
quickSelectAll	Set to `true` to allow quick selection of all displayed lookup items on `ctrl + a` keys combination.	boolean
readOnly	Defaults to `false`. Used to make the field read-only.	boolean
required	Defaults to `false`. Used to make the field required.	boolean
showClear	Set to `false` to hide the clear button. It can be used interchangeably with the `hideClear` property. No effect if `multiple` is used. Default value is `true`.	boolean
sort	Set to `true` to sort drop-down options.	boolean
style	Style object applied to the wrapper div. Used for setting the dimensions of the element.	string/object
submitOnDropdownEnterKey	Set to `true` to allow dropdown enter key events to be propagated. This is useful for submitting forms on dropdown enter key selection.	config
submitOnEnterKey	Set to `true` to allow enter key events to be propagated. This is useful for submitting forms and closing grid cell editors.	config
tabIndex	Custom tab index to be set on the field.	string
tabOnEnterKey	Set to `true` to move focus to the next field if `Enter` key is pressed.	boolean
tooltip	Tooltip configuration. For more info see Tooltips.	string/object
trackFocus	If set to `true` top level element will get additional CSS class indicating that input is focused. Used for adding special effects on focus. Default is `false`.	boolean
validationMode	Defines how to present validation errors. Default mode is `tooltip`. Other options are `help` and `help-block`. See Validation Options for more information.	string
validationParams	An structured binding for additional validation parameters. Useful if validation depends on values from other fields, e.g. confirm password. Calculated value is passed as the third argument to `onValidate`.	structure
vdomKey	Key that will be used as the key when rendering the React component.	string
viewMode	Set to `true` to switch into view mode. Same as `mode="view"`.	boolean
visible if	Visibility of the widget. Defaults to `true`.	boolean
visited	Validation errors are not shown until the user visits the field. Setting this field to `true` will cause that validation error indicators become visible immediately.	boolean

Documentation

LookupField