The simplest case of using LookupField is to select an enumeration value for an entity attribute. For example, a Role entity has a type attribute of the RoleType type, which is an enumeration. Then you can use LookupField to edit this attribute as follows:

<dsContext>
    <datasource id="roleDs" class="com.haulmont.cuba.security.entity.Role" view="_local"/>
</dsContext>
<layout>
    <lookupField datasource="roleDs" property="type"/>

Similarly, LookupField can be used to select an instance of a related entity. optionsDatasource attribute is used to create a list of options:

<dsContext>
    <datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
    <collectionDatasource id="coloursDs" class="com.company.sample.entity.Colour" view="_local">
        <query>select c from sample$Colour c</query>
    </collectionDatasource>
</dsContext>
<layout>
    <lookupField datasource="carDs" property="colour" optionsDatasource="coloursDs"/>

The list of component options can be specified arbitrarily using the setOptionsList(), setOptionsMap() and setOptionsEnum() methods, or using the XML optionsDatasource attribute.

setOptionsList() allows you to programmatically specify a list of component options. To do this, declare a component in the XML descriptor:

<lookupField id="numberOfSeatsField" datasource="modelDs" property="numberOfSeats"/>

@Inject
protected LookupField numberOfSeatsField;

@Override
public void init(Map<String, Object> params) {
    List<Integer> list = new ArrayList<>();
    list.add(2);
    list.add(4);
    list.add(5);
    list.add(7);
    numberOfSeatsField.setOptionsList(list);
}

setOptionsMap() allows you to specify string names and option values separately. For example, in the numberOfSeatsField component in the XML descriptor, specify an option map in init():

@Inject
protected LookupField numberOfSeatsField;

@Override
public void init(Map<String, Object> params) {
    Map<String, Object> map = new LinkedHashMap<>();
    map.put("two", 2);
    map.put("four", 4);
    map.put("five", 5);
    map.put("seven", 7);
    numberOfSeatsField.setOptionsMap(map);
}

setOptionsEnum() takes the class of an enumeration as a parameter. The drop-down list will show localized names of enum values, the value of the component will be an enum value.

Each drop-down list component can have an icon on the left. Create an implementation of the LookupField.OptionIconProvider interface in the screen controller and set it for the lookupField:

lookupField.setOptionIconProvider(new LookupField.OptionIconProvider<Customer>(){
    @Override
    public String getItemIcon(Customer c){
        if(c.getType()== LegalStatus.LEGAL)
            return"icons/icon-office.png";
        return"icons/icon-user.png";
    }
});

Using the filterMode attribute, option filtering type can be defined for the user input:

If the LookupField component is not required and if the related entity attribute is not declared as required, the list of component options has an empty row. If this row is selected, the component returns null. The nullName attribute allows you to specify a row to be displayed in this case instead of an empty one. Below is an example:

<lookupField datasource="carDs" property="colour" optionsDatasource="coloursDs" nullName="(none)"/>

The LookupField component is able to handle user input if there is no suitable option in the list. In this case, setNewOptionAllowed() and setNewOptionHandler() are used. For example:

@Inject
protected LookupField colourField;

@Inject
protected CollectionDatasource<Colour, UUID> coloursDs;

@Override
public void init(Map<String, Object> params) {
    colourField.setNewOptionAllowed(true);
    colourField.setNewOptionHandler(new LookupField.NewOptionHandler() {
        @Override
        public void addNewOption(String caption) {
            Colour colour = new Colour();
            colour.setName(caption);
            coloursDs.addItem(colour);
            colourField.setValue(colour);
        }
    });
}

The nullOptionVisible XML attribute sets visibility for the null option in the drop-down list. It allows you to make LookupField not required but still without the null option.

The textInputAllowed XML attribute can be used to disable filtering options from keyboard. It can be convenient for short lists. The default value is true.

The pageLength XML attribute allows you to redefine the number of options on one page of the drop-down list, specified in the cuba.gui.lookupFieldPageLength application property.

In Web Client with a Halo-based theme, you can set predefined styles to the LookupField component using the stylename attribute either in the XML descriptor or in the screen controller:

<lookupField id="lookupField"
             stylename="borderless"/>

lookupField.setStyleName(HaloTheme.LOOKUPFIELD_BORDERLESS);