Простейший вариант использования LookupField - выбор значения перечисления (enum) для атрибута сущности. Например, сущность Role имеет атрибут type типа RoleType, который является перечислением. Тогда для редактирования этого атрибута можно использовать LookupField следующим образом:

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

Аналогично можно использовать LookupField для выбора экземпляра связанной сущности. Для формирования списка опций используется атрибут optionsContainer:

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

Метод setOptionCaptionProvider() позволяет задать заголовки для строковых названий опций, отображаемых компонентом LookupField:

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

Список опций компонента может быть задан произвольно с помощью методов setOptionsList(), setOptionsMap() и setOptionsEnum(), либо с помощью XML-атрибута optionsContainer или optionsDatasource.

setOptionStyleProvider() позволяет задать отдельные стили для различных значений в выпадающем списке:

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

Каждый элемент выпадающего списка может иметь значок слева. Чтобы установить значки, используйте метод setOptionIconProvider():

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">

Если у компонента LookupField не установлен атрибут required, и если связанный атрибут сущности не объявлен как обязательный, то в списке опций компонента присутствует пустая строка, при выборе которой компонент возвращает значение null. Атрибут nullName позволяет задать строку, отображаемую в этом случае вместо пустой. Пример использования:

<lookupField dataContainer="carDc" property="colour" optionsContainer="colorsDs" nullName="(none)"/>

Компонент LookupField способен обрабатывать ввод пользователя при отсутствии подходящей опции в списке. Для этого используется метод setNewOptionHandler(). Например:

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

XML-атрибут nullOptionVisible устанавливает видимость элемента со значением null в списке опций. Может работать только если атрибут required имеет значение false.

XML-атрибут textInputAllowed используется для отключения возможности фильтрации опций с клавиатуры. Это бывает удобно для коротких списков. Значение по умолчанию - true.

XML-атрибут pageLength позволяет переопределить количество опций на одной странице выпадающего списка, заданное свойством приложения cuba.gui.lookupFieldPageLength.

В веб-клиенте с темой, основанной на Halo, к компоненту LookupField можно применить предопределенные стили. Стили задаются в XML-дексрипторе или контроллере экрана с помощью атрибута stylename:

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

lookupField.setStyleName(HaloTheme.LOOKUPFIELD_BORDERLESS);