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:

<data>
    <instance id="roleDc"
              class="com.haulmont.cuba.security.entity.Role"
              view="_local">
        <loader/>
    </instance>
</data>
<layout expand="editActions" spacing="true">
    <lookupField dataContainer="roleDc" property="type"/>
</layout>

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

<data>
    <instance id="carDc" class="com.haulmont.sample.core.entity.Car" view="carEdit">
        <loader/>
    </instance>
    <collection id="colorsDc" class="com.haulmont.sample.core.entity.Color" view="_minimal">
        <loader id="colorsDl">
            <query>
                <![CDATA[select e from sample_Color e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <lookupField dataContainer="carDc" property="color" optionsContainer="colorsDc"/>
</layout>

The setOptionCaptionProvider() method allows you to define captions for string option names displayed by LookupField component:

lookupField.setOptionCaptionProvider((item) -> item.getLocalizedName());

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

setPopupWidth() allows you to set the drop-down list’s width, which is passed to the method as a string. By using relative units (e.g., "50%") it’s possible to set the drop-down list’s width relative to the LookupField itself. By default, this width is set to null so that the drop-down list’s width can be greater than a component width to fit the content of all displayed items. By setting the value to "100%" the drop-down list’s width will be equal to the width of the LookupField.

setOptionStyleProvider() enables you to use separate style names for the the options displayed by the component:

lookupField.setOptionStyleProvider(entity -> {
    User user = (User) entity;
    switch (user.getGroup().getName()) {
        case "Company":
            return "company";
        case "Premium":
            return "premium";
        default:
            return "company";
    }
});

Each drop-down list component can have an icon on the left. Use the setOptionIconProvider() method in the screen controller:

lookupField.setOptionIconProvider(entity -> {
    if (entity.getType() == LegalStatus.LEGAL)
        return "icons/icon-office.png";
    return "icons/icon-user.png";
});

<svg version="1.1"
     id="Capa_1"
     xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     xml:space="preserve"

     style="enable-background:new 0 0 55 55;"
     viewBox="0 0 55 55"

     height="25px"
     width="25px">

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 dataContainer="carDc" property="colour" optionsContainer="colorsDs" nullName="(none)"/>

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

@Inject
private Metadata metadata;
@Inject
private LookupField<Color> colorField;
@Inject
private CollectionContainer<Color> colorsDc;

@Subscribe
protected void onInit(InitEvent event) {
    colorField.setNewOptionHandler(caption -> {
        Color color = metadata.create(Color.class);
        color.setName(caption);
        colorsDc.getMutableItems()
                .add(color);
        colorField.setValue(color);
    });
}

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);