CheckBox is a component with two states: selected or deselected.

Component’s XML-name: checkBox.

check box


Usage example:

<checkBox id="checkBox"
          caption="Create new document"/>

Selecting/deselecting the CheckBox changes its value: Boolean.TRUE or Boolean.FALSE. You can use getValue() and setValue() methods to get or set the value. Passing null to setValue() changes the value to Boolean.FALSE and unchecks the CheckBox.

Data-aware CheckBox

To create the CheckBox associated with data, use dataContainer and property attributes.

    <instance id="userDc" class="ui.ex1.entity.User">
        <checkBox dataContainer="userDc"
                  caption="User Property"/>

In the example above, the screen includes the description of the userDc data container for a User entity with the enabled attribute. The dataContainer attribute of the CheckBox component contains a reference to a data container. The property attribute contains the name of an entity attribute whose value is displayed by the CheckBox. The attribute should have a Boolean type.


The appearance of the CheckBox component can be customized using SCSS variables with $jmix-checkbox-* prefix.

Events and Handlers

To generate a handler stub in Jmix Studio, select the component in the screen descriptor XML or in the Jmix UI hierarchy panel and use the Handlers tab of the Jmix UI inspector panel.

Alternatively, you can use the Generate Handler button in the top panel of the screen controller.



Adds a validator instance to the component. The validator must throw ValidationException if the value is not valid.

@Install(to = "checkBoxValid", subject = "validator")
protected void checkBoxValidValidator(Boolean value) {
    if (!value)
        throw new ValidationException("You must accept the terms of the license");


You can use the ValueChangeListener method to track changes of the CheckBox value. For example:

private Notifications notifications;

protected void onCheckBoxValueChange(HasValue.ValueChangeEvent<Boolean> event) {
    if (Boolean.TRUE.equals(event.getValue())) {
    } else {
                .withCaption("not set")

CheckBox XML Attributes

You can view and edit attributes applicable to the component using the Jmix UI inspector panel of the Studio’s Screen Designer.