switch

switch lets users toggle a boolean setting on or off.

XML Element

switch

Java Class

Switch

Basics

LIVE DEMO

switch is an alternative to the checkbox component, designed to represent binary states clearly and intuitively. Switches are best for:

  • Toggling between two mutually exclusive options (for example, on/off).

  • Providing immediate visual feedback.

  • Enabling or disabling settings that take effect right away.

The checkbox and checkboxGroup components, on the other hand, are better suited for:

  • Selecting one or more options from a list.

  • Allowing multiple, non-exclusive choices.

  • Scenarios where changes do not take immediate effect.

An example of switch:

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

Data-aware switch

LIVE DEMO

Use the dataContainer and property attributes to bind switch to a Boolean entity attribute. The data container provides the entity instance, and property identifies the attribute to edit.

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

XML
<data>
    <instance id="customerDc"
              class="io.jmix.uisamples.entity.Customer"
              fetchPlan="_local"/>
</data>
<layout>
    <switch id="activeSwitch"
              label="Switch connected to a container"
              dataContainer="customerDc"
              property="active"/>
    <hbox>
        <span text="Value in the container:"/>
        <span id="spanValue"/>
    </hbox>
</layout>
Java
@ViewComponent
private InstanceContainer<Customer> customerDc;
@ViewComponent
private Span spanValue;

@Autowired
private Metadata metadata;

@Subscribe
public void onInit(InitEvent event) {
    Customer customer = metadata.create(Customer.class);
    customer.setActive(true);
    customerDc.setItem(customer);
}

@Subscribe("activeSwitch")
private void onActiveSwitchValueChange(ComponentValueChangeEvent<Switch, Boolean> changeEvent) {
    spanValue.setText(customerDc.getItem().isActive().toString());
}

States

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

Enabled

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

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

<switch label="Enable Dark Mode"
        value="true"
        enabled="false"/>
<switch label="Enable Dark Mode"
        value="true"
        enabled="true"/>

Read-only

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

<switch label="Enable Dark Mode"
        value="true"
        readOnly="false"/>
<switch label="Enable Dark Mode"
        value="true"
        readOnly="true"/>

Required

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

When the field is marked as required, a visual indicator appears next to the label to inform the user. If switch is initially turned on (selected) and then turned off (deselected), the field will be marked as invalid until the required condition is met again.

Like input fields, switch 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.

Attributes

The following attributes are specific to switch:

Name Description Default

enabled

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

true

readOnly

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

false

required

Set the required state of switch. See Required State.

false

value

Sets the component value.

—

The following shared attributes are supported by switch:

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

Handlers

The following handlers are specific to switch:

Name Description

ClickEvent

Fired when the user clicks the component.

The following shared handlers are supported by switch:

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent

Elements

A switch can include tooltip as its nested elements.