EntityComboBox allows users to select a single entity instance from a drop-down list and perform actions when the user clicks buttons on the right.

In fact, EntityComboBox is a hybrid of ComboBox and EntityPicker.

Component’s XML-name: entityComboBox.


Use EntityComboBox if:

  • The field value is a reference to an entity instance.

  • Users need to select a single option.

  • The list should be compact. It can be handy when the list of options is too long for RadioButtonGroup or SingleSelectList.

  • Users need filtering functionality.

  • Users need to perform some actions on the related entity instance.

EntityComboBox is a text field with a scrollable list of entity instances. It can have both custom and predefined actions:

entity combo box

To create EntityComboBox connected to data, use the dataContainer and property attributes. The optionsContainer attribute is used to create a list of options:

    <instance id="addressDc" class="ui.ex1.entity.Address"> (1)
        <fetchPlan extends="_base"> (2)
            <property name="country" fetchPlan="_instance_name"/>
    <collection id="countriesDc" class="ui.ex1.entity.Country"> (3)
        <fetchPlan extends="_base"/>
        <loader id="countriesDl">
                <![CDATA[select e from uiex1_Country e]]>
    <dataLoadCoordinator auto="true"/>
    <vbox spacing="true">
        <entityComboBox id="countryField"
                        optionsContainer="countriesDc"> (4)
                <action id="lookup" type="entity_lookup"/>
                <action id="clear" type="entity_clear"/>
1 InstanceContainer for the Address entity.
2 Inline fetch plan of the entity instance located in the container.
3 CollectionContainer for the Country entity.
4 countryField gets countriesDc as an options container so that the list of countries is displayed.

In the example above, the screen defines the addressDc data container for the Address entity having the country attribute. In the entityComboBox element, the dataContainer attribute contains a link to the addressDc data container, and the property attribute refers to the country entity attribute. The entity attribute should be a reference to an entity. In the following example, it is Country.


There are no default actions for EntityComboBox. You need to explicitly add all necessary actions, for example:

<entityComboBox dataContainer="addressDc"
        <action id="lookup" type="entity_lookup"/>
        <action id="clear" type="entity_clear"/>

Detailed information on defining custom and predefined actions is available in the Actions section for EntityPicker.

Handling User Input

The user can enter a value that is not in the initial drop-down list and then select the item later without entering it again. To handle it, you should use enterPressHandler.

You can generate the enterPressHandler implementation stub using Studio.

private CollectionContainer<Country> countriesDc;

private EntityComboBox<Country> countryEntityComboBox;

private DataContext dataContext;

@Install(to = "countryEntityComboBox", subject = "enterPressHandler")
private void countryEntityComboBoxEnterPressHandler(HasEnterPressHandler.EnterPressEvent enterPressEvent) {
    Country country = dataContext.create(Country.class); (1)
    country.setName(enterPressEvent.getText()); (2)
    countriesDc.getMutableItems().add(country); (3)
1 Create a new instance and merge it into the context.
2 Set the name of the newly created country entity.
3 Add merged entity.

enterPressHandler is invoked when the user enters a value and presses Enter. In this case, a new value is added to the list of options and becomes available for later use.