Package com.vaadin.flow.component.checkbox

Class Checkbox

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.AbstractField<C,T>
com.vaadin.flow.component.AbstractSinglePropertyField<Checkbox,Boolean>
com.vaadin.flow.component.checkbox.Checkbox
All Implemented Interfaces:
com.vaadin.flow.component.AttachNotifier, com.vaadin.flow.component.BlurNotifier<Checkbox>, com.vaadin.flow.component.ClickNotifier<Checkbox>, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.Focusable<Checkbox>, com.vaadin.flow.component.FocusNotifier<Checkbox>, com.vaadin.flow.component.HasAriaLabel, com.vaadin.flow.component.HasElement, com.vaadin.flow.component.HasEnabled, com.vaadin.flow.component.HasHelper, com.vaadin.flow.component.HasLabel, com.vaadin.flow.component.HasSize, com.vaadin.flow.component.HasStyle, com.vaadin.flow.component.HasValidation, com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>,Boolean>, com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>,Boolean>, HasClientValidation, HasTooltip, HasValidationProperties, InputField<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>,Boolean>, com.vaadin.flow.data.binder.HasValidator<Boolean>, Serializable
@Tag("vaadin-checkbox") @NpmPackage(value="@vaadin/polymer-legacy-adapter",version="24.8.1") @NpmPackage(value="@vaadin/checkbox",version="24.8.1") @JsModule("@vaadin/polymer-legacy-adapter/style-modules.js") @JsModule("@vaadin/checkbox/src/vaadin-checkbox.js") public class Checkbox extends com.vaadin.flow.component.AbstractSinglePropertyField<Checkbox,Boolean> implements com.vaadin.flow.component.ClickNotifier<Checkbox>, com.vaadin.flow.component.Focusable<Checkbox>, com.vaadin.flow.component.HasAriaLabel, HasClientValidation, HasValidationProperties, com.vaadin.flow.data.binder.HasValidator<Boolean>, InputField<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>,Boolean>
Checkbox is an input field representing a binary choice.

Checkbox also has an indeterminate mode, see isIndeterminate() for more info.

Use CheckboxGroup to group related items. Individual checkboxes should be used for options that are not related to each other in any way.

Validation

Checkbox comes with a built-in validation mechanism that verifies that the field is selected when required is enabled.

Validation is triggered whenever the user toggles the checkbox. Programmatic toggling triggers validation as well. If validation fails, the component is marked as invalid and an error message is displayed below the input.

The required error message can be configured using either Checkbox.CheckboxI18n.setRequiredErrorMessage(String) or HasValidationProperties.setErrorMessage(String).

For more advanced validation that requires custom rules, you can use Binder. Please note that Binder provides its own API for the required validation, see asRequired().

However, if Binder doesn't fit your needs and you want to implement fully custom validation logic, you can disable the built-in validation by setting setManualValidation(boolean) to true. This will allow you to control the invalid state and the error message manually using HasValidationProperties.setInvalid(boolean) and HasValidationProperties.setErrorMessage(String) API.

Author:
Vaadin Ltd
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Checkbox.CheckboxI18n
    The internationalization properties for Checkbox.

    Nested classes/interfaces inherited from class com.vaadin.flow.component.AbstractField

    com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<C extends com.vaadin.flow.component.Component,V extends Object>

    Nested classes/interfaces inherited from interface com.vaadin.flow.component.BlurNotifier

    com.vaadin.flow.component.BlurNotifier.BlurEvent<C extends com.vaadin.flow.component.Component>

    Nested classes/interfaces inherited from interface com.vaadin.flow.component.FocusNotifier

    com.vaadin.flow.component.FocusNotifier.FocusEvent<C extends com.vaadin.flow.component.Component>

    Nested classes/interfaces inherited from interface com.vaadin.flow.component.shared.HasClientValidation

    HasClientValidation.ClientValidatedEvent

    Nested classes/interfaces inherited from interface com.vaadin.flow.component.HasValue

    com.vaadin.flow.component.HasValue.ValueChangeEvent<V extends Object>, com.vaadin.flow.component.HasValue.ValueChangeListener<E extends com.vaadin.flow.component.HasValue.ValueChangeEvent<?>>

  • Constructor Summary

    Constructors
    Constructor
    Description
    Checkbox()
    Default constructor.
    Checkbox(boolean initialValue)
    Constructs a checkbox with the initial value.
    Checkbox(boolean initialValue, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>> listener)
    Constructs a checkbox with the initial value and value change listener.
    Checkbox(String labelText)
    Constructs a checkbox with the initial label text.
    Checkbox(String labelText, boolean initialValue)
    Constructs a checkbox with the initial value.
    Checkbox(String labelText, boolean initialValue, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>> listener)
    Constructs a checkbox with the initial value, label text and value change listener.
    Checkbox(String label, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>> listener)
    Constructs a checkbox with the initial label text and value change listener.

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<String>
    getAriaLabel()
     
    Optional<String>
    getAriaLabelledBy()
     
    com.vaadin.flow.data.binder.Validator<Boolean>
    getDefaultValidator()
     
    Checkbox.CheckboxI18n
    getI18n()
    Gets the internationalization object previously set for this component.
    String
    getLabel()
    Get the current label text.
    boolean
    isAutofocus()
    Get the state for the auto-focus property of the checkbox.
    boolean
    isIndeterminate()
    Get the indeterminate state of the checkbox.
    boolean
    isRequiredIndicatorVisible()
    Gets whether the user is required to select the checkbox.
    void
    setAriaLabel(String ariaLabel)
     
    void
    setAriaLabelledBy(String ariaLabelledBy)
     
    void
    setAutofocus(boolean autofocus)
    Set the checkbox to be input focused when the page loads.
    void
    setI18n(Checkbox.CheckboxI18n i18n)
    Sets the internationalization object for this component.
    void
    setIndeterminate(boolean indeterminate)
    Set the indeterminate state of the checkbox.
    void
    setLabel(String label)
    Set the current label text of this checkbox.
    void
    setLabelComponent(com.vaadin.flow.component.Component component)
    Replaces the label content with the given label component.
    void
    setManualValidation(boolean enabled)
     
    void
    setRequiredIndicatorVisible(boolean required)
    Sets whether the user is required to select the checkbox.
    protected void
    validate()
    Validates the current value against the constraints and sets the invalid property and the errorMessage property based on the result.

    Methods inherited from class com.vaadin.flow.component.AbstractSinglePropertyField

    getSynchronizationRegistration, hasValidValue, setPresentationValue, setSynchronizedEvent

    Methods inherited from class com.vaadin.flow.component.AbstractField

    addValueChangeListener, getEmptyValue, getValue, isEmpty, setModelValue, setValue, valueEquals

    Methods inherited from class com.vaadin.flow.component.Component

    addListener, findAncestor, fireEvent, from, get, getChildren, getElement, getEventBus, getId, getListeners, getLocale, getParent, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onAttach, onDetach, onEnabledStateChanged, removeFromParent, scrollIntoView, scrollIntoView, set, setElement, setId, setVisible

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface com.vaadin.flow.component.AttachNotifier

    addAttachListener

    Methods inherited from interface com.vaadin.flow.component.BlurNotifier

    addBlurListener

    Methods inherited from interface com.vaadin.flow.component.ClickNotifier

    addClickListener, addClickShortcut, addDoubleClickListener, addSingleClickListener

    Methods inherited from interface com.vaadin.flow.component.DetachNotifier

    addDetachListener

    Methods inherited from interface com.vaadin.flow.component.Focusable

    addFocusShortcut, blur, focus, getTabIndex, setTabIndex

    Methods inherited from interface com.vaadin.flow.component.FocusNotifier

    addFocusListener

    Methods inherited from interface com.vaadin.flow.component.shared.HasClientValidation

    addClientValidatedEventListener

    Methods inherited from interface com.vaadin.flow.component.HasElement

    getElement

    Methods inherited from interface com.vaadin.flow.component.HasEnabled

    isEnabled, setEnabled

    Methods inherited from interface com.vaadin.flow.component.HasHelper

    getHelperComponent, getHelperText, setHelperComponent, setHelperText

    Methods inherited from interface com.vaadin.flow.component.HasSize

    getHeight, getHeightUnit, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getWidth, getWidthUnit, setHeight, setHeight, setHeightFull, setMaxHeight, setMaxHeight, setMaxWidth, setMaxWidth, setMinHeight, setMinHeight, setMinWidth, setMinWidth, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthFull

    Methods inherited from interface com.vaadin.flow.component.HasStyle

    addClassName, addClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName

    Methods inherited from interface com.vaadin.flow.component.shared.HasTooltip

    getTooltip, setTooltipText

    Methods inherited from interface com.vaadin.flow.component.shared.HasValidationProperties

    getErrorMessage, isInvalid, setErrorMessage, setInvalid

    Methods inherited from interface com.vaadin.flow.data.binder.HasValidator

    addValidationStatusChangeListener

    Methods inherited from interface com.vaadin.flow.component.HasValue

    addValueChangeListener, clear, getEmptyValue, getOptionalValue, getValue, isEmpty, setValue

    Methods inherited from interface com.vaadin.flow.component.HasValueAndElement

    isReadOnly, setReadOnly

  • Constructor Details

    • Checkbox

      public Checkbox()
      Default constructor.

    • Checkbox

      public Checkbox(String labelText)
      Constructs a checkbox with the initial label text.
      Parameters:
      labelText - the label text to set
      See Also:

    • Checkbox

      public Checkbox(boolean initialValue)
      Constructs a checkbox with the initial value.
      Parameters:
      initialValue - the initial value
      See Also:
      • AbstractField.setValue(Object)

    • Checkbox

      public Checkbox(String labelText, boolean initialValue)
      Constructs a checkbox with the initial value.
      Parameters:
      labelText - the label text to set
      initialValue - the initial value
      See Also:

    • Checkbox

      public Checkbox(String label, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>> listener)
      Constructs a checkbox with the initial label text and value change listener.
      Parameters:
      label - the label text to set
      listener - the value change listener to add
      See Also:

    • Checkbox

      public Checkbox(boolean initialValue, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>> listener)
      Constructs a checkbox with the initial value and value change listener.
      Parameters:
      initialValue - the initial value
      listener - the value change listener to add
      See Also:
      • AbstractField.setValue(Object)
      • AbstractField.addValueChangeListener(ValueChangeListener)

    • Checkbox

      public Checkbox(String labelText, boolean initialValue, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>> listener)
      Constructs a checkbox with the initial value, label text and value change listener.
      Parameters:
      labelText - the label text to set
      initialValue - the initial value
      listener - the value change listener to add
      See Also:
      • setLabel(String)
      • AbstractField.setValue(Object)
      • AbstractField.addValueChangeListener(ValueChangeListener)

  • Method Details

    • setRequiredIndicatorVisible

      public void setRequiredIndicatorVisible(boolean required)
      Sets whether the user is required to select the checkbox. When required, an indicator appears next to the label and the field invalidates if the checkbox is first selected and then deselected.

      NOTE: The required indicator is only visible when the field has a label, see setLabel(String).

      Specified by:
      setRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>,Boolean>
      Specified by:
      setRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>,Boolean>
      Parameters:
      required - true to make the field required, false otherwise
      See Also:

    • isRequiredIndicatorVisible

      public boolean isRequiredIndicatorVisible()
      Gets whether the user is required to select the checkbox.
      Specified by:
      isRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>,Boolean>
      Specified by:
      isRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Checkbox,Boolean>,Boolean>
      Returns:
      true if the field is required, false otherwise
      See Also:

    • getLabel

      public String getLabel()
      Get the current label text.
      Specified by:
      getLabel in interface com.vaadin.flow.component.HasLabel
      Returns:
      the current label text

    • setLabel

      public void setLabel(String label)
      Set the current label text of this checkbox.
      Specified by:
      setLabel in interface com.vaadin.flow.component.HasLabel
      Parameters:
      label - the label text to set

    • setLabelComponent

      public void setLabelComponent(com.vaadin.flow.component.Component component)
      Replaces the label content with the given label component.
      Parameters:
      component - the component to be added to the label.
      Since:
      23.1

    • setAriaLabel

      public void setAriaLabel(String ariaLabel)
      Specified by:
      setAriaLabel in interface com.vaadin.flow.component.HasAriaLabel

    • getAriaLabel

      public Optional<String> getAriaLabel()
      Specified by:
      getAriaLabel in interface com.vaadin.flow.component.HasAriaLabel

    • setAriaLabelledBy

      public void setAriaLabelledBy(String ariaLabelledBy)
      Specified by:
      setAriaLabelledBy in interface com.vaadin.flow.component.HasAriaLabel

    • getAriaLabelledBy

      public Optional<String> getAriaLabelledBy()
      Specified by:
      getAriaLabelledBy in interface com.vaadin.flow.component.HasAriaLabel

    • setAutofocus

      public void setAutofocus(boolean autofocus)
      Set the checkbox to be input focused when the page loads.
      Parameters:
      autofocus - the boolean value to set

    • isAutofocus

      public boolean isAutofocus()
      Get the state for the auto-focus property of the checkbox.

      This property is not synchronized automatically from the client side, so the returned value may not be the same as in client side.

      Returns:
      the autofocus property from the checkbox

    • setIndeterminate

      public void setIndeterminate(boolean indeterminate)
      Set the indeterminate state of the checkbox.

      NOTE: As according to the HTML5 standard, this has only effect on the visual appearance, not on the checked value!

      Parameters:
      indeterminate - the boolean value to set
      See Also:

    • isIndeterminate

      @Synchronize(property="indeterminate", value="indeterminate-changed") public boolean isIndeterminate()
      Get the indeterminate state of the checkbox. The default value is false.

      An indeterminate checkbox is neither checked nor unchecked. A typical use case is a “Select All” checkbox indicating that some, but not all, items are selected. When the user clicks an indeterminate checkbox, it is no longer indeterminate, and the checked value also changes.

      NOTE: As according to the HTML5 standard, this has only effect on the visual appearance, not on the checked value!

      Returns:
      the indeterminate property from the checkbox

    • setManualValidation

      public void setManualValidation(boolean enabled)
      Specified by:
      setManualValidation in interface com.vaadin.flow.component.HasValidation

    • getDefaultValidator

      public com.vaadin.flow.data.binder.Validator<Boolean> getDefaultValidator()
      Specified by:
      getDefaultValidator in interface com.vaadin.flow.data.binder.HasValidator<Boolean>

    • validate

      protected void validate()
      Validates the current value against the constraints and sets the invalid property and the errorMessage property based on the result. If a custom error message is provided with HasValidationProperties.setErrorMessage(String), it is used. Otherwise, the error message defined in the i18n object is used.

      The method does nothing if the manual validation mode is enabled.

    • getI18n

      public Checkbox.CheckboxI18n getI18n()
      Gets the internationalization object previously set for this component.

      NOTE: Updating the instance that is returned from this method will not update the component if not set again using setI18n(CheckboxI18n)

      Returns:
      the i18n object or null if no i18n object has been set

    • setI18n

      public void setI18n(Checkbox.CheckboxI18n i18n)
      Sets the internationalization object for this component.
      Parameters:
      i18n - the i18n object, not null