The SearchPickerField component is used to search for entity instances according to the entered string. A user should enter a few characters and press Enter. If several matches have been found, all of them will be displayed in a drop-down list. If only one instance matches the search query, it immediately becomes a component value. SearchPickerField also enables performing actions by clicking on buttons on the right.

gui searchPickerFieldOverlap

XML name of the component: searchPickerField.

gui SearchPickerField dia

The component is implemented for Web Client and Desktop Client.

  • To use SearchPickerField component, you need to create collectionDatasource and specify a query, which contains corresponding search conditions. Condition must contain a parameter named custom$searchString. This parameter will be populated with a substring entered by the user. A data source with a search condition should be defined in the optionsDatasource attribute of the component. For example:

        <datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
        <collectionDatasource id="coloursDs" class="com.company.sample.entity.Colour" view="_local">
                select c from sample$Colour c
                where c.name like :(?i)custom$searchString
        <searchPickerField datasource="carDs" property="colour" optionsDatasource="coloursDs"/>

    In this case, the component will look for instances of Colour entity according to the occurrence of the substring in its name attribute. The (?i) prefix is used for case-insensitive search (see Case-Insensitive Search for a Substring). The selected value will be set in the colour attribute of the Car entity located in the carDs datasource.

  • Using the minSearchStringLength attribute the minimum number of characters, which the user should enter to search for values, can be defined.

  • In the screen controller, two component methods can be implemented that will be invoked:

    • If the number of entered characters is less than the value of minSearchStringLength attribute.

    • If the search of characters entered by the user has returned no results.

    Below is an example of implementing methods to display messages to the user:

    private SearchPickerField colourField;
    public void init(Map<String, Object> params) {
        colourField.setSearchNotifications(new SearchField.SearchNotifications() {
            public void notFoundSuggestions(String filterString) {
                showNotification("No colours found for search string: " + filterString,
            public void needMinSearchStringLength(String filterString, int minSearchStringLength) {
                showNotification("Minimum length of search string is " + minSearchStringLength,
  • SearchPickerField implements LookupField and PickerField interfaces. Thus, it inherits the same functionality except the default list of actions added when defining the component in XML: for SearchPickerField these are lookup lookupBtn and open openBtn actions.