radioButtonGroup

radioButtonGroup allows users to select a single value from a predefined list of items using radio buttons.

XML Element

radioButtonGroup

Java Class

JmixRadioButtonGroup

Basics

LIVE DEMO

The simplest case of using radioButtonGroup is to select an enumeration value for an entity attribute.

<radioButtonGroup id="verticalRadioButtonGroup"
               label="Vertical"
               themeNames="vertical"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>
<radioButtonGroup id="horizontalRadioButtonGroup"
               label="Horizontal"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>

In the example above, the User entity has the onboardingStatus attribute of the OnboardingStatus type, which is an enumeration.

Items from a Data Container

LIVE DEMO

radioButtonGroup can fetch a list of items from a data container using the itemsContainer attribute. For example:

<data>
    <collection id="productsDc"
                class="io.jmix.uisamples.entity.Product"
                fetchPlan="_local">
        <loader id="productsLoader">
            <query>
                <![CDATA[select e from Product e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <radioButtonGroup id="radioButtonGroup"
                   itemsContainer="productsDc"
                   themeNames="vertical"/>
</layout>

In this case, radioButtonGroup will display instance names of the Hobby entity, located in the hobbiesDc data container, and its getValue() method will return the currently selected entity instance.

Building Items

LIVE DEMO

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

Items from a List

<radioButtonGroup id="radioButtonGroupWithList"
                  label="Items List"
                  themeNames="vertical"/>

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

@ViewComponent
protected JmixRadioButtonGroup<Integer> radioButtonGroupWithList;
    radioButtonGroupWithList.setItems(getItemsList());
protected List<Integer> getItemsList() {
    return List.of(2, 4, 5, 7);
}

Items with Custom Labels

<radioButtonGroup id="radioButtonGroupWithMap"
                  label="Items Map"
                  themeNames="vertical"/>

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

@ViewComponent
protected JmixRadioButtonGroup<Integer> radioButtonGroupWithMap;
    ComponentUtils.setItemsMap(radioButtonGroupWithMap, getItemsMap());
protected Map<Integer, String> getItemsMap() {
    Map<Integer, String> itemsMap = new LinkedHashMap<>();
    itemsMap.put(2, "Two");
    itemsMap.put(4, "Four");
    itemsMap.put(5, "Five");
    itemsMap.put(7, "Seven");
    return itemsMap;
}

Enumeration Items

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

The following example demonstrates the declarative approach.

<radioButtonGroup id="radioButtonGroupWithEnum"
                  label="Items Enum"
                  themeNames="vertical"/>

The example below uses the programmatic approach.

@ViewComponent
protected JmixRadioButtonGroup<CustomerGrade> radioButtonGroupWithEnum;
    radioButtonGroupWithEnum.setItems(CustomerGrade.class);

Item Enabled Provider

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

@Install(to = "radioButtonGroup", subject = "itemEnabledProvider")
private boolean radioButtonGroupItemEnabledProvider(OnboardingStatus onboardingStatus) {
    if (onboardingStatus != null) {
        return onboardingStatus.getId() != 30;
    }
    return true;
}

Customizing Item Labels

itemLabelGenerator allows you to customize how items are displayed in the radioButtonGroup component. 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 = "statusRadioButtonGroup", subject = "itemLabelGenerator")
private String statusRadioButtonGroupItemLabelGenerator(
        final OnboardingStatus t) {
    return metadataTools.format(t).toUpperCase();
}

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;

@Autowired
private FileStorage fileStorage;

@Supply(to = "rbgRenderer", subject = "renderer")
private ComponentRenderer<HorizontalLayout, User> rbgRendererRenderer() {
    return new ComponentRenderer<>(user -> {
        FileRef fileRef = user.getPicture();
        HorizontalLayout row = uiComponents.create(HorizontalLayout.class);
        row.setAlignItems(FlexComponent.Alignment.END);
        if (fileRef != null) {
            Image image = uiComponents.create(Image.class);
            image.setWidth("30px");
            image.setHeight("30px");
            image.setClassName("user-picture");
            InputStreamDownloadHandler handler =
                    DownloadHandler.fromInputStream(event ->
                            new DownloadResponse(
                                    fileStorage.openStream(fileRef),
                                    fileRef.getFileName(),
                                    fileRef.getContentType(),
                                    -1
                            ));
            image.setSrc(handler);
            row.add(image);
        }
        row.add(new Span(user.getFirstName() + ", " + user.getLastName()));
        return row;
    });
}

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

Theme Variants

LIVE DEMO

Use the themeNames attribute to apply one or more theme variants.

Variant Description Supported By

vertical

Displays items vertically.

Lumo

helper-above-field

Renders the helper text above the field, below the label.

Aura, Lumo

Attributes

The following attributes are specific to radioButtonGroup:

Name Description Default

itemsContainer

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

—

itemsEnum

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

—

The following shared attributes are supported by radioButtonGroup:

id - alignSelf - ariaLabel - ariaLabelledBy - classNames - colspan - css - dataContainer - datatype - enabled - errorMessage - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - property - readOnly - required - requiredMessage - themeNames - visible - width

Handlers

The following handlers are specific to radioButtonGroup:

Name Description

itemEnabledProvider

itemEnabledProvider is applied to each item of this radioButtonGroup to determine whether the item should be enabled (true) or disabled (false). See Item Enabled Provider.

itemLabelGenerator

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

renderer

Sets the item renderer for this radio button group. See Rendering Items.

validator

Validates the component value.

The following shared handlers are supported by radioButtonGroup:

AttachEvent - ClientValidatedEvent - ComponentValueChangeEvent - DetachEvent - statusChangeHandler

Elements

A radioButtonGroup can include fragmentRenderer and tooltip as its nested elements.

See Also