SuggestionField allows searching for certain values according to a string entered by a user.

It can use any types of options: entities, strings, or enum values. SuggestionField does not have action buttons. The list of options is loaded in the background according to the logic defined by the application developer on the server-side.

Component’s XML-name: suggestionField.


Use SuggestionField if:

  • Users need to select a single option.

  • The number of options in the list of suggested values is too large to use ComboBox or EntityComboBox.

  • You want to provide high-performance search in the database without loading much data to the UI layer.

SuggestionField is an input text field with the additional functionality: a user enters a few characters, and if several matches have been found, all of them will be displayed in a drop-down list. SuggestionField refreshes the list of options on each entered symbol.

suggestion field

To create SuggestionField connected to data, use the dataContainer and property attributes:

    <instance id="addressDc" class="ui.ex1.entity.Address"> (1)
        <fetchPlan extends="_base"> (2)
            <property name="country" fetchPlan="_instance_name"/>
    <suggestionField id="countryField"
                     inputPrompt="Start typing the country name">
1 InstanceContainer for the Address entity.
2 Inline fetch plan of the entity instance located in the container.

To enable SuggestionField suggestions, you should use the search executor, for example:

private DataManager dataManager;

@Install(to = "countryField", subject = "searchExecutor")
protected List<Country> countryFieldSearchExecutor(String searchString,
                                                   Map<String, Object> searchParams) {
    return dataManager.load(Country.class)
            .query(" like ?1 order by", "(?i)%"
                    + searchString + "%")


SearchExecutor is a functional interface that contains a single method: List<E> search(String searchString, Map<String, Object> searchParams).

Use the searchString parameter to filter candidates using the string entered by the user.

In the most common case, it is sufficient to set a SearchExecutor implementation to the component.

SearchExecutor can return any types of options, for example, entities, strings, or enum values.

  • Entities

    First, declare a component in the XML descriptor:

    <suggestionField id="entityField" visible="false"
                     inputPrompt="Start typing the country name"/>

    Then set SearchExecutor to the component:

    private DataManager dataManager;
    @Install(to = "entityField", subject = "searchExecutor")
    private List<Country> entityFieldSearchExecutor(String searchString,
                                                    Map<String, Object> searchParams) {
        return dataManager.load(Country.class)
                .query(" like ?1 order by", "(?i)%"
                        + searchString + "%")

    You can generate the SearchExecutor implementation stub using Studio.

  • Strings

    @Install(to = "stringField", subject = "searchExecutor")
    private List stringFieldSearchExecutor(String searchString,
                                           Map<String, Object> searchParams) {
        return Stream.of("John", "Andy", "Dora", "Martin", "Peter", "George")
                .filter(str -> StringUtils.containsIgnoreCase(str, searchString))
  • Enum

    private Messages messages;
    @Install(to = "enumField", subject = "searchExecutor")
    private List enumFieldSearchExecutor(String searchString,
                                         Map<String, Object> searchParams) {
        return Stream.of(Hobby.values())
                .filter(status ->

The search() method is executed in a background thread, so it cannot access visual components or data containers used by visual components. Call DataManager or a service directly, or process and return data loaded to the screen beforehand.


You can use the escapeForLike() method to search for the values that contain special symbols:

private DataManager dataManager;

@Install(to = "entitySuggestionField", subject = "searchExecutor")
private List<Customer> entitySuggestionFieldSearchExecutor(String searchString,
                                                           Map<String, Object> searchParams) {
    searchString = QueryUtils.escapeForLike(searchString);
    return dataManager.load(Customer.class)
            .query("e.firstName like ?1 escape '\\' order by e.firstName", "(?i)%"
                    + searchString + "%")

Suggestions Managing


The asyncSearchDelayMs attribute sets the delay between the last key press action and asynchronous search.


The minSearchStringLength attribute sets the minimal string length, which is required to perform suggestions search.

If you set minSearchStringLength = 1 the suggestion popup is displayed almost immediately after the user starts typing, and too many suggestions appear at first. If you search through a large amount of data, make SuggestionField less sensitive, for example:


The popupWidth attribute sets the width of the suggestion popup.

Possible options:

  • auto - the popup width will be equal to the maximum width of suggestions.

  • parent - the popup width will be equal to the width of the main component.

  • absolute (for example, "170px") or relative (for example, "50%") value.


The suggestionsLimit attribute sets the limit of suggestions to be displayed. The default value is 10.

Events and Handlers

To generate a handler stub in Jmix Studio, select the component in the screen descriptor XML or in the Jmix UI hierarchy panel and use the Handlers tab of the Jmix UI inspector panel.

Alternatively, you can use the Generate Handler button in the top panel of the screen controller.




See the example of programmatic registration in the Handling User Input section for ComboBox.

EnterPressHandler can be provided declaratively using the @Install annotation in the screen controller. See this example in the Handling User Input section for EntityComboBox.


See Formatter.


OptionsStyleProvider allows you to manage additional style names for the suggested options displayed by SuggestionField:

@Install(to = "customerSuggestionField", subject = "optionStyleProvider")
private String customerSuggestionFieldOptionStyleProvider(Customer customer) {
    if (customer != null) {
        switch (customer.getLevel()) {
            case SILVER:
                return "silver-level";
            case GOLD:
                return "gold-level";
            case PLATINUM:
                return "platinum-level";
            case DIAMOND:
                return "diamond-level";
    return null;

Then you should define the item styles set in the application theme. Detailed information on creating a theme is available in Themes. Style names representing in the controller, together with prefixes identifying each item, form CSS selectors. For example:

.silver-level {
    background-color: #c0c0c0;
    color: black;

.gold-level {
    background-color: #fdd017;
    color: black;

.platinum-level {
    background-color: #e5e4e2;
    color: black;

.diamond-level {
    background-color: #b9f2ff;
    color: black;
suggestion field styles



See Validator.


SuggestionField XML Attributes

SuggestionField XML Elements