Components API

To generate handler method stubs in Jmix Studio, use the Generate Handler button in the top panel of the screen controller code. Or you can select the component in the screen descriptor layout and use the Handlers tab of the Component Inspector panel.


It is a handler that is invoked when the user clicks on a special ? icon near the field. Click handler has priority over the context help text. That is, no tooltip with context help text will be shown if the handler is set.

In the following example, we will consider creating an input dialog that is called in the ContextHelpIconClickHandler. The dialog collects data to form an address string.

private TextField<String> addressField;

private Dialogs dialogs;

@Install(to = "addressField", subject = "contextHelpIconClickHandler")
private void addressFieldContextHelpIconClickHandler(
        HasContextHelp.ContextHelpIconClickEvent event) {
            .withCaption("Get values")
                    InputParameter.entityParameter("city", City.class)
            .withCloseListener(closeEvent -> {
                if (closeEvent.closedWith(DialogOutcome.OK)) {
                    City city = closeEvent.getValue("city");
                    String street = closeEvent.getValue("street");
                    String building = closeEvent.getValue("building");
                    Integer zip = closeEvent.getValue("zip");
                    addressField.setValue(city + ", " + street + ", " +
                            building + ", " + zip);
context help handler

To register the event handler programmatically, use the setContextHelpIconClickHandler() component method.


EnterPressListener is sent when the user press Enter button:

private Notifications notifications;

public void onTextFieldEnterPress(TextInputField.EnterPressEvent event) {
            .withCaption("Enter pressed")

Programmatic registration of the event handler: use the addEnterPressListener() component method.


ExpandedStateChangeEvent is sent when the component’s expanded state is changed.

Example of subscribing to the event for filter defined in the screen XML with the filter id:

public void onFilterExpandedStateChange(Collapsable.ExpandedStateChangeEvent event) {
            .withCaption("Expanded: " + event.isExpanded())

Programmatic registration of the event handler: use the addExpandedStateChangeListener() component method.


OptionCaptionProvider delegate method allows you to change displayed caption of items in the component:

@Install(to = "twinColumn", subject = "optionCaptionProvider")
private String twinColumnOptionCaptionProvider(Employee employee) {
    return employee.getName() + ", salary: " + employee.getSalary();
twin column caption provider

Programmatic usage: call the setOptionCaptionProvider() component method.


OptionsStyleProvider delegate method allows you to manage additional style names for options displayed by component:

@Install(to = "ratingField", subject = "optionStyleProvider")
private String ratingFieldOptionStyleProvider(Integer rating) {
    if (rating != null) {
        switch (rating) {
            case 2:
                return "poor";
            case 3:
                return "average";
            case 4:
                return "good";
            case 5:
                return "excellent";
    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:

.v-filterselect-item-poor {
    background-color: #f4f1ec;
    color: black;

.v-filterselect-item-average {
    background-color: #e5ddce;
    color: black;

.v-filterselect-item-good {
    background-color: #ecd7d2;
    color: black;

.v-filterselect-item-excellent {
    background-color: #c69c96;
    color: black;
combo box style

To register the options style provider programmatically, use the setOptionStyleProvider() component method.


ValueChangeEvent is sent when the user finished the manipulations with component. For example, after the Enter press or when the component loses focus. An event has the following methods:

  • getPrevValue() returns the value of the component before the change.

  • getValue() returns the current value of the component.

private Notifications notifications;

public void onTextFieldValueChange(HasValue.ValueChangeEvent event) {
            .withCaption("Before: " + event.getPrevValue() +
                    ". After: " + event.getValue())

To register the event handler programmatically, use the addValueChangeListener() component method.