checkbox

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

XML Element

checkbox

Java Class

JmixCheckbox

Basics

LIVE DEMO

An example of checkbox:

<checkbox id="carField" label="I have a car"/>

Data-aware checkbox

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.

The following example produces a data-aware checkbox. The entity attribute must be of Boolean type.

<data>
    <instance id="customerDc"
              class="io.jmix.uisamples.entity.Customer"
              fetchPlan="_local"/>
</data>
<layout>
    <checkbox id="activeCheckbox"
              label="Checkbox connected to a container"
              dataContainer="customerDc"
              property="active"/>
    <hbox>
        <span text="Value in the container:"/>
        <span id="spanValue"/>
    </hbox>
</layout>

The customerDc instance container loads a Customer entity with its local attributes. The dataContainer attribute binds the component to that container, and the property attribute selects the Boolean active attribute.

States

checkbox can exist in several states that define its visual appearance and functionality.

Enabled

  • Enabled: The checkbox is interactive and responsive to user input. Users can click on it to change its state.

  • Disabled: The checkbox is inactive and cannot be interacted with by the user. Visually, it is often grayed out to indicate its inactive state.

<checkbox label="The enabled checkbox"
          value="true"
          enabled="true"/>
<checkbox label="The disabled checkbox"
          enabled="false"
          value="true"/>

Read-only

The readOnly attribute controls whether the checkbox component can be interacted with by the user. If set to true, checkbox becomes read-only, meaning the user cannot change its state.

<checkbox label="The readOnly checkbox"
          value="true"
          readOnly="true"/>
<checkbox label="The editable checkbox"
          readOnly="false"
          value="true"/>

Indeterminate

The indeterminate attribute controls whether checkbox is in an indeterminate state. This state represents a situation where checkbox is neither fully checked nor fully unchecked.

Visually, it changes the checkbox’s appearance to indicate an indeterminate state.

As according to the HTML5 standard, this has only effect on the visual appearance, not on the checked value. 
<checkbox label="With indeterminate state = true"
          value="false"
          indeterminate="true"/>
<checkbox label="With indeterminate state = false"
          indeterminate="false"
          value="false"/>

Required

A checkbox can be configured as required using its required attribute or by binding it to a mandatory attribute with @NotNull validation.

Like input fields, a checkbox will only pass @NotNull validation if it is not empty (i.e., if it is checked). The default behavior can be modified using the jmix.ui.component.checkbox-required-state-initialization-enabled property, which allows the unchecked state to be treated as false.

Click Events

The com.vaadin.flow.component.ClickEvent is fired when the component is clicked. This handler must specify one of the following three subjects to detect the number of clicks related to the event.

  • click - fires the event whenever the component is clicked.

  • singleClick - fires the event after a timeout to ensure it is not a double click.

  • doubleClick - fires the event when the component is double-clicked.

For example:

com.vaadin.flow.component.ClickEvent is sent when the user clicks checkbox.

@Autowired
private Notifications notifications;

@Subscribe(id = "checkbox", subject = "clickListener")
public void onCheckboxClick(final ClickEvent<JmixCheckbox> event) {
    if (event.getSource().getValue()){
        notifications.show("Set");
    } else {
        notifications.show("Not set");
    }
}

Attributes

The following attributes are specific to checkbox:

Name Description Default

enabled

Sets the component explicitly disabled or enabled. See Enabled State.

true

indeterminate

Set the indeterminate state of checkbox. See Indeterminate State.

false

readOnly

Specifies whether the checkbox component is in read-only mode. See Read-Only State.

false

required

Set the required state of checkbox. See Required State.

false

value

Sets the component value.

—

The following shared attributes are supported by checkbox:

id - alignSelf - ariaLabel - ariaLabelledBy - autofocus - classNames - clickShortcut - colspan - css - dataContainer - focusShortcut - height - label - maxHeight - maxWidth - minHeight - minWidth - property - tabIndex - visible - width

Handlers

The following handlers are specific to checkbox:

Name Description

ClickEvent

The com.vaadin.flow.component.ClickEvent is fired when the component is clicked. See Click Events.

The following shared handlers are supported by checkbox:

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent

Elements

A checkbox can include tooltip as its nested elements.

See Also