This is a component that allows a user to select a single value from a list of options using radio buttons.

gui RadioButtonGroup

XML name of the component: radioButtonGroup.

The RadioButtonGroup component is implemented for Web Client.

The list of component options can be specified using the setOptions(), setOptionsList(), setOptionsMap() and setOptionsEnum() methods, or using an optionsContainer attribute.

  • The simplest case of using RadioButtonGroup is to select an enumeration value for an entity attribute. For example, a Role entity has type attribute of the RoleType type, which is an enumeration. Then you can use RadioButtonGroup to display this attribute as follows, using the optionsEnum attribute:

    <radioButtonGroup optionsEnum="com.haulmont.cuba.security.entity.RoleType"

    The setOptionsEnum() takes a class of enumeration as a parameter. The options list will consist of localized names of enum values, the value of the component will be an enum value.


    The same result will be achieved using the setOptions() method which enables working with all types of options:

    radioButtonGroup.setOptions(new EnumOptions<>(RoleType.class));
  • setOptionsList() enables specifying programmatically a list of component options. To do this, declare a component in the XML descriptor:

    <radioButtonGroup id="radioButtonGroup"/>

    Then inject the component into the controller and specify a list of options for it:

    private RadioButtonGroup<Integer> radioButtonGroup;
    protected void onInit(InitEvent event) {
        List<Integer> list = new ArrayList<>();

    The component will be as follows:

    gui RadioButtonGroup 2

    Depending on the selected option, the getValue() method of the component will return Integer values: 2, 4, 5, 7.

  • setOptionsMap() enables specifying string names and option values separately. For example, we can set the following options map for the radioButtonGroup component injected in the controller:

    private RadioButtonGroup<Integer> radioButtonGroup;
    protected void onInit(InitEvent event) {
        Map<String, Integer> map = new LinkedHashMap<>();
        map.put("two", 2);
        map.put("four", 4);
        map.put("five", 5);
        map.put("seven", 7);

    The component will be as follows:

    gui RadioButtonGroup 3

    Depending on the selected option, the getValue() method of the component will return Integer values: 2, 4, 5, 7, and not the strings that are displayed on the screen.

  • The component can take a list of options from a data container. For this purpose, the optionsContainer attribute is used. For example:

        <collection id="employeesCt" class="com.company.demo.entity.Employee" view="_minimal">
                <query><![CDATA[select e from demo_Employee e]]></query>
        <radioButtonGroup optionsContainer="employeesCt"/>

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

    gui RadioButtonGroup 4

    With the help of captionProperty attribute entity attribute to be used instead of an instance name for string option names can be defined.

    Programmatically, you can define the options container using the setOptions() method of RadioButtonGroup interface:

    private RadioButtonGroup<Employee> radioButtonGroup;
    private CollectionContainer<Employee> employeesCt;
    protected void onInit(InitEvent event) {
        radioButtonGroup.setOptions(new ContainerOptions<>(employeesCt));

You can use OptionDescriptionProvider to generate optional descriptions (tooltips) for the options. It can be used via the setOptionDescriptionProvider() method or the @Install annotation:

private RadioButtonGroup<Product> radioButtonGroup;

public void onInit(InitEvent event) {
    radioButtonGroup.setOptionDescriptionProvider(product -> "Price: " + product.getPrice());
@Install(to = "radioButtonGroup", subject = "optionDescriptionProvider")
private String radioButtonGroupOptionDescriptionProvider(Experience experience) {
    switch (experience) {
        case HIGH:
            return "Senior";
        case COMMON:
            return "Middle";
            return "Junior";

The orientation attribute defines the orientation of group elements. By default, elements are arranged vertically. The horizontal value sets the horizontal orientation.