select

Basics

select is similar to comboBox.

Use select when:

  • You don’t need user input and items filtering.

  • The list should be compact. It can be useful when the list of items is too long for radioButtonGroup.

The simplest case of using select is to select a value from an enumeration:

<select itemsEnum="com.company.onboarding.entity.DayOfWeek"
        label="Select the day of week"/>
select basics

Data Binding

LIVE DEMO

Data binding refers to linking a visual component to a data container. Changes in the visual component or corresponding data container can trigger updates to one another. See Using Data Components for more details.

By default, Jmix Studio generates select when creating an entity detail view with an enum attribute. For example, the User entity has the onboardingStatus attribute of the OnboardingStatus type, which is an enumeration.

<data>
    <instance id="userDc"
              class="com.company.onboarding.entity.User">
        <fetchPlan extends="_base"/>
        <loader id="userDl"/>
    </instance>
</data>
<layout>
    <formLayout id="form" dataContainer="userDc">
        <select id="onboardingStatusField"
                property="onboardingStatus"/>
    </formLayout>
</layout>

The following example demonstrates how to use the select component to select the department the user belongs to:

<data>
    <instance class="com.company.onboarding.entity.User"
              id="userDc"> (1)
        <fetchPlan extends="_base"> (2)
            <property name="department" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="userDl"/>
    </instance>
    <collection class="com.company.onboarding.entity.Department"
                id="departmentsDc"> (3)
        <fetchPlan extends="_base"/>
        <loader id="departmentsDl">
            <query>
                <![CDATA[select e from Department e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/> (4)
</facets>
<layout>
    <select dataContainer="userDc"
            property="department"
            itemsContainer="departmentsDc"/> (5)
</layout>
1 Data container to hold the User instance which is currently being edited.
2 Fetch plan extended to retrieve a collection of Department instances that will be available for selection.
3 Data container to hold a collection of all existing Department instances.
4 Data load coordinator to automatically supply the component with instances to select from.
5 Binding the component to a data container and property. Specifying a collection of instances for selection using the itemsContainer attribute.

Building Items

To set the list of select items, use the following methods:

Items List

<select id="selectItems" datatype="int"/>

The setItems() method allows you to specify component items programmatically.

@ViewComponent
private JmixSelect<Integer> selectItems;

@Subscribe
public void onInit(final InitEvent event) {
    selectItems.setItems(1, 2, 3, 4, 5);
}

Items Map

<select id="selectMaps" datatype="int"/>

ComponentUtils.setItemsMap() allows you to specify a string label for each item value explicitly.

@ViewComponent
private JmixSelect<Integer> selectMaps;

@Subscribe
public void onInit(final InitEvent event) {
    Map<Integer, String> map = new LinkedHashMap<>();
    map.put(2, "Poor");
    map.put(3, "Average");
    map.put(4, "Good");
    map.put(5, "Excellent");
    ComponentUtils.setItemsMap(selectMaps, map);
}

Items Enum

You can use either a declarative or programmatic approach to set the values of an enum as select items.

The following example demonstrates the declarative approach.

<select id="selectEnum"
        itemsEnum="com.company.onboarding.entity.DayOfWeek"/>

The example below uses the programmatic approach.

@ViewComponent
private JmixSelect<DayOfWeek> selectEnum;

@Subscribe
public void onInit(final InitEvent event) {
    selectEnum.setItems(DayOfWeek.class);
}

Disabled Items

Items can be disabled to indicate they are unavailable for selection, but they could be selected under different conditions.

itemEnabledProvider allows you to dynamically control the enabled state of individual items based on specific conditions. Disabled items appear grayed out and cannot be selected by the user. All items are enabled by default.

@Install(to = "select", subject = "itemEnabledProvider")
private boolean selectItemEnabledProvider(final Department department) {
    return department == null || department.getHrManager() != null;
}

Empty Selection Item

The select component offers the ability to display an empty selection item, which is helpful in scenarios where a default value or a "no selection" state is desired.

The emptySelectionAllowed attribute sets whether the user is allowed to select nothing. When set true a special empty item is shown to the user.

The empty selection item can be customized with the emptySelectionCaption attribute.

<select id="sizeSelect"
        emptySelectionAllowed="true"
        emptySelectionCaption="Unknown size"
        datatype="string"/>

The emptySelectionCaption attribute sets the empty selection caption when emptySelectionAllowed = true. The caption is shown for the empty selection item in the drop-down.

When the empty selection item is selected, the select shows the value provided by itemLabelGenerator for the null item, or the string set with the placeholder attribute or an empty string if not placeholder is set.

@Install(to = "sizeSelect", subject = "itemLabelGenerator")
private String sizeSelectItemLabelGenerator(final String t) {
    return t != null ? t : sizeSelect.getEmptySelectionCaption();
}

Customizing Item Labels

itemLabelGenerator allows you to customize how items are displayed in the dropdown list. This gives you control over the text that users see, enabling you to present information in a more user-friendly or context-specific manner.

@Install(to = "customItemsSelect", subject = "itemLabelGenerator")
private String customItemsSelectItemLabelGenerator(final Department t) {
    return t.getHrManager() != null
            ? t.getName() + "[Manager: " + t.getHrManager().getFirstName() +
            " " + t.getHrManager().getLastName() + "]"
            : t.getName();
}

itemLabelGenerator controls both the labels for each item in the dropdown list and the text displayed in the select component’s input field when an item is selected.

textRenderer controls the labels displayed in the dropdown list for each item.

@Install(to = "departmentSelect", subject = "textRenderer")
private String departmentSelectTextRenderer(final Department t) {
    return t.getName() + ", number #" + t.getNum();
}
textRenderer doesn’t affect the text displayed in the select component’s input field after an item is selected.

Use when you want to customize the labels shown in the dropdown list. This is helpful for improving clarity, adding additional information, or adapting the labels based on the selected object’s properties.

Rendering Items

It is possible to customize the render of items. The renderer is applied to each item to create a component which represents the item.

You can use the setRenderer() method or the @Supply annotation for it.

@Autowired
private UiComponents uiComponents;

@Supply(to = "selectWithRenderer", subject = "renderer")
private ComponentRenderer<Button, Department> selectWithRendererRenderer() {
    return new ComponentRenderer<>(department -> {
        Button button = uiComponents.create(Button.class);
        button.setText(department.getName());
        button.setIcon(VaadinIcon.DESKTOP.create());
        return button;
    });
}

Alternatively, you can render items using a nested fragmentRenderer element. Refer to the Fragment Renderer section for more information.

Overlay

Overlay is a semi-transparent or opaque layer that is used to create a dropdown list of items.

The overlayClass attribute allows you to add custom CSS classes to the overlay element.

<select itemsEnum="com.company.onboarding.entity.DayOfWeek"
        overlayClass="my-custom-overlay"/>

Define a custom style in your css file:

vaadin-select-overlay.my-custom-overlay::part(overlay){
    background-color: #ecfcf9;
    border-radius: 5px;
}

Theme Variants

Use the themeNames attribute to adjust text alignment, helper text placement, and component size.

Alignment

Choose among three alignment options: align-left (default), align-right, align-center.

select alignment
XML code 
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        themeNames="align-left"
        helperText="The align-left alignment"/>
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        themeNames="align-center"
        helperText="The align-center alignment"/>
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        themeNames="align-right"
        helperText="The align-right alignment"/>

Helper Text Position

Setting helper-above-field will move the helper text from its default position below the field to above it.

select helper above field
XML code 
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        label="Onboarding status"
        helperText="Helper text with helper-above-field"
        themeNames="helper-above-field"/>
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        label="Onboarding status"
        helperText="Helper text without helper-above-field"/>

Size

Two size options are available: the default size and small.

select size
XML code 
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        helperText="Default size"/>
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        themeNames="small"
        helperText="Small size"/>

Attributes

In Jmix there are many common attributes that serve the same purpose for all components.

The following are attributes specific to select:

Name

Description

Default

emptySelectionAllowed

Sets whether the user is allowed to select nothing. See Empty Selection Item.

false

emptySelectionCaption

Sets the empty selection caption when emptySelectionAllowed = true. See Empty Selection Item.

Empty string ""

itemsContainer

Defines the data container holding a list of items. The component displays the instance name of an entity. See the second example in Data Binding.

itemsEnum

Defines the enumeration class for creating a list of items. See Items Enum.

overlayClass

Defines a space-delimited list of CSS class names to set on the overlay element. See Overlay.

Handlers

In Jmix there are many common handlers that are configured in the same way for all components.

The following are handlers specific to select.

To generate a handler stub in Jmix Studio, use the Handlers tab of the Jmix UI inspector panel or the Generate Handler action available in the top panel of the view class and through the Code → Generate menu (Alt+Insert / Cmd+N).

Name

Description

InvalidChangeEvent

com.vaadin.flow.component.select.Select.InvalidChangeEvent is sent when the invalid state changes.

OpenedChangeEvent

com.vaadin.flow.component.select.Select.OpenedChangeEvent is sent when the overlay opened state changes.

itemEnabledProvider

itemEnabledProvider is applied to each item of this select to determine whether the item should be enabled (true) or disabled (false). See Disabled Items.

itemLabelGenerator

Allows you to customize the labels displayed for each item. See Customizing Item Labels.

renderer

Sets the item renderer for this select group. The renderer is applied to each item to create a component which represents the item option in the select’s drop down. See Rendering Items.

textRenderer

It is a renderer for converting the item to a string. See Customizing Item Labels.

See Also

See the Vaadin Docs for more information.