Простейший вариант использования 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.

setPopupWidth() позволяет установить ширину выпадающего списка, которая передается в метод в виде строки. Используя относительное значение (например, "50%"), можно установить ширину выпадающего списка относительно ширины LookupField. По умолчанию эта ширина имеет значение null, поэтому ширина выпадающего списка может быть больше ширины компонента, для того чтобы соответствовать содержимому всех отображаемых элементов. Установив значение "100%", ширина выпадающего списка будет равна ширине LookupField.

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