Package com.vaadin.flow.component.checkbox

Class Switch

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.AbstractField<Switch,Boolean>
com.vaadin.flow.component.AbstractSinglePropertyField<Switch,Boolean>
com.vaadin.flow.component.checkbox.Switch
All Implemented Interfaces:
com.vaadin.flow.component.AttachNotifier, com.vaadin.flow.component.BlurNotifier<Switch>, com.vaadin.flow.component.ClickNotifier<Switch>, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.Focusable<Switch>, com.vaadin.flow.component.FocusNotifier<Switch>, 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.HasTheme, com.vaadin.flow.component.HasValidation, com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,Boolean>,Boolean>, com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,Boolean>,Boolean>, com.vaadin.flow.component.shared.HasThemeVariant<SwitchVariant>, com.vaadin.flow.component.shared.HasTooltip, com.vaadin.flow.component.shared.HasValidationProperties, com.vaadin.flow.component.shared.InputField<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,Boolean>,Boolean>, com.vaadin.flow.data.binder.HasValidator<Boolean>, Serializable
@Tag("vaadin-switch") @NpmPackage(value="@vaadin/switch", version="25.3.0-alpha4") @JsModule("@vaadin/switch/src/vaadin-switch.js") public class Switch extends com.vaadin.flow.component.AbstractSinglePropertyField<Switch,Boolean> implements com.vaadin.flow.component.ClickNotifier<Switch>, com.vaadin.flow.component.Focusable<Switch>, com.vaadin.flow.component.HasAriaLabel, com.vaadin.flow.component.shared.HasValidationProperties, com.vaadin.flow.data.binder.HasValidator<Boolean>, com.vaadin.flow.component.shared.InputField<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,Boolean>,Boolean>, com.vaadin.flow.component.shared.HasThemeVariant<SwitchVariant>
Switch is an input field representing a binary on/off choice.

This component is experimental and needs to be enabled with the com.vaadin.experimental.switchComponent feature flag.

Switch is functionally equivalent to Checkbox, but it is presented as an on/off toggle and is intended for a single setting that takes effect immediately. Unlike Checkbox, Switch has no indeterminate state.

Validation

Switch 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 switch. 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 Switch.SwitchI18n.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.

Since:
25.3
Author:
Vaadin Ltd
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Switch.SwitchI18n
    The internationalization properties for Switch.

    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>

    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.HasValue

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

  • Constructor Summary

    Constructors
    Constructor
    Description
    Switch()
    Default constructor.
    Switch(boolean initialValue)
    Constructs a switch with the initial value.
    Switch(boolean initialValue, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,Boolean>> listener)
    Constructs a switch with the initial value and value change listener.
    Switch(String labelText)
    Constructs a switch with the initial label text.
    Switch(String labelText, boolean initialValue)
    Constructs a switch with the initial label text and value.
    Switch(String labelText, boolean initialValue, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,Boolean>> listener)
    Constructs a switch with the initial value, label text and value change listener.
    Switch(String label, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,Boolean>> listener)
    Constructs a switch 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()
     
    Switch.SwitchI18n
    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 switch.
    boolean
    isRequiredIndicatorVisible()
    Gets whether the user is required to switch on the control.
    protected void
    onAttach(com.vaadin.flow.component.AttachEvent attachEvent)
     
    void
    setAriaLabel(String ariaLabel)
     
    void
    setAriaLabelledBy(String ariaLabelledBy)
     
    void
    setAutofocus(boolean autofocus)
    Set the switch to be input focused when the page loads.
    void
    setI18n(Switch.SwitchI18n i18n)
    Sets the internationalization object for this component.
    void
    setLabel(String label)
    Set the current label text of this switch.
    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 switch on the control.
    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, bindValue, getEmptyValue, getValue, isEmpty, setModelValue, setValue, valueEquals

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

    addListener, bindVisible, findAncestor, fireEvent, from, get, getChildren, getElement, getEventBus, getId, getListeners, getLocale, getParent, getTestId, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onDetach, onEnabledStateChanged, removeFromParent, scrollIntoView, scrollIntoView, set, setElement, setId, setTestId, 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, focus, getTabIndex, setTabIndex

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

    addFocusListener

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

    setAriaLabelledBy

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

    getElement

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

    bindEnabled, isEnabled, setEnabled

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

    bindHelperText, getHelperComponent, getHelperText, setHelperComponent, setHelperText

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

    bindHeight, bindWidth, 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, bindClassName, bindClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName

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

    addThemeName, addThemeNames, bindThemeName, bindThemeNames, getThemeName, getThemeNames, hasThemeName, removeThemeName, removeThemeNames, setThemeName, setThemeName

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

    addThemeVariants, bindThemeVariant, bindThemeVariants, removeThemeVariants, setThemeVariant, setThemeVariants, setThemeVariants

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

    getTooltip, setTooltipMarkdown, 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, bindValue, clear, getEmptyValue, getOptionalValue, getValue, isEmpty, setValue

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

    bindReadOnly, bindRequiredIndicatorVisible, isReadOnly, setReadOnly

  • Constructor Details

    • Switch

      public Switch()
      Default constructor.

    • Switch

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

    • Switch

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

    • Switch

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

    • Switch

      public Switch(String label, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,Boolean>> listener)
      Constructs a switch 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:

    • Switch

      public Switch(boolean initialValue, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,Boolean>> listener)
      Constructs a switch 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)

    • Switch

      public Switch(String labelText, boolean initialValue, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,Boolean>> listener)
      Constructs a switch 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

    • onAttach

      protected void onAttach(com.vaadin.flow.component.AttachEvent attachEvent)
      Overrides:
      onAttach in class com.vaadin.flow.component.Component

    • setRequiredIndicatorVisible

      public void setRequiredIndicatorVisible(boolean required)
      Sets whether the user is required to switch on the control. When required, an indicator appears next to the label and the field invalidates if the switch is first turned on and then turned off.

      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<Switch,Boolean>,Boolean>
      Specified by:
      setRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,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 switch on the control.
      Specified by:
      isRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,Boolean>,Boolean>
      Specified by:
      isRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<Switch,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 switch.
      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.

    • 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 switch 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 switch.
      Returns:
      the autofocus property from the switch

    • 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 Switch.SwitchI18n 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(SwitchI18n)

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

    • setI18n

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