com.vaadin.flow.component.radiobutton.
Class RadioButtonGroup<T>
All Implemented Interfaces:
AttachNotifier
, DetachNotifier
, HasAriaLabel
, HasElement
, HasEnabled
, HasHelper
, HasLabel
, HasSize
, HasStyle
, HasTheme
, HasValidation
, HasValue<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
, HasValueAndElement<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
, HasClientValidation
, HasThemeVariant<RadioGroupVariant>
, HasTooltip
, HasValidationProperties
, InputField<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
, HasValidator<T>
, HasDataView<T,
, HasListDataView<T,
, SingleSelect<RadioButtonGroup<T>,
, Serializable
Radio Button Group allows the user to select exactly one value from a list of related but mutually exclusive options.
Validation
Radio Button Group comes with a built-in validation mechanism that verifies
that a radio button is selected when
required
is enabled. Validation
is triggered whenever the user selects a radio button or the value is updated
programmatically. In practice, however, the required error can only occur if
the value is cleared programmatically. This is because radio buttons, by
design, don't allow users to clear a selection through UI interaction. If the
required error occurs, the component is marked as invalid and an error
message is displayed below the group.
The required error message can be configured using either
RadioButtonGroup.RadioButtonGroupI18n.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 ClassesModifier and TypeClassDescriptionstatic class
The internationalization properties for
RadioButtonGroup
.Nested classes/interfaces inherited from class com.vaadin.flow.component.AbstractField
AbstractField.ComponentValueChangeEvent<C extends Component,
V> 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
HasValue.ValueChangeEvent<V>, HasValue.ValueChangeListener<E extends HasValue.ValueChangeEvent<?>>
-
Constructor Summary
ConstructorsConstructorDescriptionDefault constructor.
RadioButtonGroup
(HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>, T>> listener) Constructs a radio button group with a value change listener.
RadioButtonGroup
(String label) Creates an empty radio button group with the defined label.
RadioButtonGroup
(String label, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>, T>> listener) Constructs a radio button group with the defined label and a value change listener.
RadioButtonGroup
(String label, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>, T>> listener, T... items) Constructs a radio button group with the defined label, a value change listener and populated with the items in the array.
RadioButtonGroup
(String label, Collection<T> items) Creates a radio button group with the defined label and populated with the items in the collection.
RadioButtonGroup
(String label, T... items) Creates a radio button group with the defined label and populated with the items in the array.
-
Method Summary
Modifier and TypeMethodDescriptionGets the aria-label of the component.
Gets the aria-labelledby of the component
DataProvider<T,
?> Gets the data provider used by this RadioButtonGroup.
Returns a validator that checks the state of the Value.
Gets the generic data view for the RadioButtonGroup.
getI18n()
Gets the internationalization object previously set for this component.
Returns the item enabled predicate.
Gets the item label generator that is used to produce the strings shown in the radio button group for each item.
ComponentRenderer<? extends Component,
T> Returns the item component renderer.
getLabel()
String used for the label element.
Gets the list data view for the RadioButtonGroup.
Gets the selection preservation mode.
protected boolean
Checks whether the element property has a value that can be converted to the model type.
boolean
Returns whether this
HasValue
is in read-only mode or not.boolean
Alias for
isRequiredIndicatorVisible()
boolean
Gets whether the user is required to select a radio button.
protected void
onAttach
(AttachEvent attachEvent) Called when the component is attached to a UI.
protected void
onDetach
(DetachEvent detachEvent) Called when the component is detached from a UI.
void
onEnabledStateChanged
(boolean enabled) Handle component enable state when the enabled state changes.
void
setAriaLabel
(String ariaLabel) Set the aria-label of the component to the given text.
void
setAriaLabelledBy
(String labelledBy) Set the aria-labelledby of the component.
void
setDataProvider
(DataProvider<T, ?> dataProvider) Sets a generic data provider for the RadioButtonGroup to use.
void
Sets the internationalization object for this component.
void
setItemEnabledProvider
(SerializablePredicate<T> itemEnabledProvider) Sets the item enabled predicate for this radio button group.
void
setItemLabelGenerator
(ItemLabelGenerator<T> itemLabelGenerator) Sets the item label generator that is used to produce the strings shown in the radio button group for each item.
setItems
(DataProvider<T, Void> dataProvider) Set a generic data provider for the component to use and returns the base
DataView
that provides API to get information on the items.setItems
(InMemoryDataProvider<T> inMemoryDataProvider) Sets an in-memory data provider for the component to use
setItems
(ListDataProvider<T> dataProvider) Sets a ListDataProvider for the component to use and returns a
ListDataView
that provides information and allows operations on the items.void
Sets the label for the field.
void
setManualValidation
(boolean enabled) Sets whether manual validation mode is enabled for the component.
void
setReadOnly
(boolean readOnly) Sets the read-only mode of this
HasValue
to given mode.void
setRenderer
(ComponentRenderer<? extends Component, T> renderer) Sets the item renderer for this radio button group.
void
setRequired
(boolean required) Alias for
setRequiredIndicatorVisible(boolean)
.void
setRequiredIndicatorVisible
(boolean required) Sets whether the user is required to select a radio button.
void
setSelectionPreservationMode
(SelectionPreservationMode selectionPreservationMode) Sets the selection preservation mode.
void
Sets the value of this object.
protected void
validate()
Validates the current value against the constraints and sets the
invalid
property and theerrorMessage
property based on the result.protected boolean
valueEquals
(T value1, T value2) Compares two value instances to each other to determine whether they are equal.
Methods inherited from class com.vaadin.flow.component.AbstractSinglePropertyField
getSynchronizationRegistration, setPresentationValue, setSynchronizedEvent
Methods inherited from class com.vaadin.flow.component.AbstractField
addValueChangeListener, getEmptyValue, getValue, isEmpty, setModelValue
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, 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.DetachNotifier
addDetachListener
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.data.provider.HasListDataView
setItems, setItems
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.HasTheme
addThemeName, addThemeNames, getThemeName, getThemeNames, hasThemeName, removeThemeName, removeThemeNames, setThemeName, setThemeName
Methods inherited from interface com.vaadin.flow.component.shared.HasThemeVariant
addThemeVariants, removeThemeVariants
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
-
Constructor Details
-
RadioButtonGroup
public RadioButtonGroup()Default constructor. Creates an empty radio button group.
-
RadioButtonGroup
Creates an empty radio button group with the defined label.
Parameters:
label
- the label describing the radio button groupSee Also:
-
RadioButtonGroup
Creates a radio button group with the defined label and populated with the items in the collection.
Parameters:
label
- the label describing the radio button groupitems
- the items to be shown in the list of the radio button groupSee Also:
-
RadioButtonGroup
Creates a radio button group with the defined label and populated with the items in the array.
Parameters:
label
- the label describing the radio button groupitems
- the items to be shown in the list of the radio button groupSee Also:
-
RadioButtonGroup
public RadioButtonGroup(HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>, T>> listener) Constructs a radio button group with a value change listener.
Parameters:
listener
- the value change listener to addSee Also:
-
RadioButtonGroup
public RadioButtonGroup(String label, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>, T>> listener) Constructs a radio button group with the defined label and a value change listener.
Parameters:
label
- the label describing the radio button grouplistener
- the value change listener to addSee Also:
-
RadioButtonGroup
@SafeVarargs public RadioButtonGroup(String label, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>, T>> listener, T... items) Constructs a radio button group with the defined label, a value change listener and populated with the items in the array.
Parameters:
label
- the label describing the radio button grouplistener
- the value change listener to additems
- the items to be shown in the list of the radio button groupSee Also:
-
-
Method Details
-
setItems
Description copied from interface:
HasDataView
Set a generic data provider for the component to use and returns the base
DataView
that provides API to get information on the items.This method should be used only when the data provider type is not either
ListDataProvider
orBackEndDataProvider
.Specified by:
setItems
in interfaceHasDataView<T,
Void, RadioButtonGroupDataView<T>> Parameters:
dataProvider
- DataProvider instance to use, notnull
Returns:
DataView providing information on the data
-
setItems
Description copied from interface:
HasDataView
Sets an in-memory data provider for the component to use
Note! Using a
ListDataProvider
instead of aInMemoryDataProvider
is recommended to get access toListDataView
API by usingHasListDataView.setItems(ListDataProvider)
.Specified by:
setItems
in interfaceHasDataView<T,
Void, RadioButtonGroupDataView<T>> Parameters:
inMemoryDataProvider
- InMemoryDataProvider to use, notnull
Returns:
DataView providing information on the data
-
setItems
Description copied from interface:
HasListDataView
Sets a ListDataProvider for the component to use and returns a
ListDataView
that provides information and allows operations on the items.Specified by:
setItems
in interfaceHasListDataView<T,
RadioButtonGroupListDataView<T>> Parameters:
dataProvider
- ListDataProvider providing items to the component.Returns:
ListDataView providing access to the items
-
getListDataView
Gets the list data view for the RadioButtonGroup. This data view should only be used when the items are in-memory and set with:
If the items are not in-memory an exception is thrown.Specified by:
getListDataView
in interfaceHasListDataView<T,
RadioButtonGroupListDataView<T>> Returns:
the list data view that provides access to the data bound to the RadioButtonGroup
-
getGenericDataView
Gets the generic data view for the RadioButtonGroup. This data view should only be used when
getListDataView()
is not applicable for the underlying data provider.Specified by:
getGenericDataView
in interfaceHasDataView<T,
Void, RadioButtonGroupDataView<T>> Returns:
the generic DataView instance implementing
RadioButtonGroupDataView
-
hasValidValue
protected boolean hasValidValue()Description copied from class:
AbstractSinglePropertyField
Checks whether the element property has a value that can be converted to the model type. Property changes from the element will be ignored if this method returns
false
. The default implementation always returntrue
.Overrides:
hasValidValue
in classAbstractSinglePropertyField<RadioButtonGroup<T>,
T> Returns:
true
if the element property value can be converted to the model type; otherwisefalse
-
setDataProvider
Sets a generic data provider for the RadioButtonGroup to use.
Use this method when none of the
setItems
methods are applicable, e.g. when having a data provider with filter that cannot be transformed toDataProvider<T, Void>
.Parameters:
dataProvider
- DataProvider instance to use, notnull
-
setItemLabelGenerator
Sets the item label generator that is used to produce the strings shown in the radio button group for each item. By default,
String.valueOf(Object)
is used.Setting an item label generator removes any previously set item renderer.
Parameters:
itemLabelGenerator
- the item label provider to use, not null -
getItemLabelGenerator
Gets the item label generator that is used to produce the strings shown in the radio button group for each item.
Returns:
the item label generator used, not null
-
setValue
Description copied from interface:
HasValue
Sets the value of this object. If the new value is not equal to
getValue()
, fires a value change event. May throwIllegalArgumentException
if the value is not acceptable.Implementation note: the implementing class should document whether null values are accepted or not, and override
HasValue.getEmptyValue()
if the empty value is notnull
.Specified by:
setValue
in interfaceHasValue<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
T>, T> Overrides:
setValue
in classAbstractField<RadioButtonGroup<T>,
T> Parameters:
value
- the new value -
onAttach
Description copied from class:
Component
Called when the component is attached to a UI.
This method is invoked before the
Make sure to callAttachEvent
is fired for the component.super.onAttach
when overriding this method. -
onDetach
Description copied from class:
Component
Called when the component is detached from a UI.
This method is invoked before the
DetachEvent
is fired for the component.Make sure to call
super.onDetach
when overriding this method. -
getDataProvider
Gets the data provider used by this RadioButtonGroup.
To get information and control over the items in the RadioButtonGroup, use either
getListDataView()
orgetGenericDataView()
instead.Returns:
the data provider used by this RadioButtonGroup
-
getItemEnabledProvider
Returns the item enabled predicate.
Returns:
the item enabled predicate
See Also:
-
setItemEnabledProvider
Sets the item enabled predicate for this radio button group. The predicate is applied to each item to determine whether the item should be enabled (
true
) or disabled (false
). Disabled items are displayed as grayed out and the user cannot select them. The default predicate always returns true (all the items are enabled).Parameters:
itemEnabledProvider
- the item enable predicate, notnull
-
getItemRenderer
Returns the item component renderer.
Returns:
the item renderer
See Also:
-
setRenderer
Sets the item renderer for this radio button group. The renderer is applied to each item to create a component which represents the item.
Note: Component acts as a label to the button and clicks on it trigger the radio button. Hence interactive components like DatePicker or ComboBox cannot be used.
Parameters:
renderer
- the item renderer, notnull
-
onEnabledStateChanged
public void onEnabledStateChanged(boolean enabled) Description copied from class:
Component
Handle component enable state when the enabled state changes.
By default this sets or removes the 'disabled' attribute from the element. This can be overridden to have custom handling.
Overrides:
onEnabledStateChanged
in classComponent
Parameters:
enabled
- the new enabled state of the component -
setReadOnly
public void setReadOnly(boolean readOnly) Description copied from interface:
HasValue
Sets the read-only mode of this
HasValue
to given mode. The user can't change the value when in read-only mode.A
HasValue
with a visual component in read-only mode typically looks visually different to signal to the user that the value cannot be edited.Specified by:
setReadOnly
in interfaceHasValue<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
T>, T> Specified by:
setReadOnly
in interfaceHasValueAndElement<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
T>, T> Parameters:
readOnly
- a boolean value specifying whether the component is put read-only mode or not -
isReadOnly
public boolean isReadOnly()Description copied from interface:
HasValue
Returns whether this
HasValue
is in read-only mode or not.Specified by:
isReadOnly
in interfaceHasValue<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
T>, T> Specified by:
isReadOnly
in interfaceHasValueAndElement<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
T>, T> Returns:
false
if the user can modify the value,true
if not. -
setRequiredIndicatorVisible
public void setRequiredIndicatorVisible(boolean required) Sets whether the user is required to select a radio button. When required, an indicator appears next to the label and the field invalidates if the selection is cleared programmatically.
NOTE: The required indicator is only visible when the field has a label, see
setLabel(String)
.Specified by:
setRequiredIndicatorVisible
in interfaceHasValue<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
T>, T> Specified by:
setRequiredIndicatorVisible
in interfaceHasValueAndElement<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
T>, T> Parameters:
required
-true
to make the field required,false
otherwiseSee Also:
-
isRequiredIndicatorVisible
public boolean isRequiredIndicatorVisible()Gets whether the user is required to select a radio button.
Specified by:
isRequiredIndicatorVisible
in interfaceHasValue<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
T>, T> Specified by:
isRequiredIndicatorVisible
in interfaceHasValueAndElement<AbstractField.ComponentValueChangeEvent<RadioButtonGroup<T>,
T>, T> Returns:
true
if the field is required,false
otherwiseSee Also:
-
isRequired
public boolean isRequired()Alias for
isRequiredIndicatorVisible()
Returns:
true
if the field is required,false
otherwise -
setRequired
public void setRequired(boolean required) Alias for
setRequiredIndicatorVisible(boolean)
.Parameters:
required
-true
to make the field required,false
otherwise -
setLabel
Sets the label for the field.
-
getLabel
String used for the label element.
-
getSelectionPreservationMode
Gets the selection preservation mode.
Returns:
the selection preservation mode
See Also:
-
setAriaLabel
Description copied from interface:
HasAriaLabel
Set the aria-label of the component to the given text.
This method should not be used if
HasAriaLabel.setAriaLabelledBy(String)
is also used. If both attributes are present, aria-labelledby will take precedence over aria-label.Specified by:
setAriaLabel
in interfaceHasAriaLabel
Parameters:
ariaLabel
- the aria-label text to set ornull
to clear -
getAriaLabel
Description copied from interface:
HasAriaLabel
Gets the aria-label of the component.
Specified by:
getAriaLabel
in interfaceHasAriaLabel
Returns:
an optional aria-label of the component if no aria-label has been set
-
setAriaLabelledBy
Description copied from interface:
HasAriaLabel
Set the aria-labelledby of the component. The value must be a valid id attribute of another element that labels the component. The label element must be in the same DOM scope of the component, otherwise screen readers may fail to announce the label content properly.
This method should not be used if
HasAriaLabel.setAriaLabel(String)
is also used. If both attributes are present, aria-labelledby will take precedence over aria-label.Specified by:
setAriaLabelledBy
in interfaceHasAriaLabel
Parameters:
labelledBy
- the string with the id of the element that will be used as label ornull
to clear -
getAriaLabelledBy
Description copied from interface:
HasAriaLabel
Gets the aria-labelledby of the component
Specified by:
getAriaLabelledBy
in interfaceHasAriaLabel
Returns:
an optional aria-labelledby of the component if no aria-labelledby has been set
-
valueEquals
Compares two value instances to each other to determine whether they are equal. Equality is used to determine whether to update internal state and fire an event when
setValue(Object)
orAbstractField.setModelValue(Object, boolean)
is called. Subclasses can override this method to define an alternative comparison method instead ofObject.equals(Object)
.Overrides:
valueEquals
in classAbstractField<RadioButtonGroup<T>,
T> Parameters:
value1
- the first instancevalue2
- the second instanceReturns:
true
if the instances are equal; otherwisefalse
-
setManualValidation
public void setManualValidation(boolean enabled) Description copied from interface:
HasValidation
Sets whether manual validation mode is enabled for the component.
When enabled, the component doesn't perform its built-in constraint validation on value change, blur, and other events. This allows manually controlling the invalid state and error messages using the
HasValidation.setInvalid(boolean)
andHasValidation.setErrorMessage(String)
methods. Manual mode is helpful when there is a need for a totally custom validation logic that cannot be achieved with Binder.Example:
Field field = new Field(); field.setManualValidation(true); field.addValueChangeListener(event -> { if (Objects.equal(event.getValue(), "")) { field.setInvalid(true); field.setErrorMessage("The field is required."); } else { field.setInvalid(false); } });
For components that don't have built-in validation, the method has no effect.
Specified by:
setManualValidation
in interfaceHasValidation
Parameters:
enabled
- whether to enable manual validation mode. -
getDefaultValidator
Description copied from interface:
HasValidator
Returns a validator that checks the state of the Value. This should be overridden for components with internal value conversion or validation, e.g. when the user is providing a string that has to be parsed into a date. An invalid input from user will be exposed to a
Binder
and can be seen as a validation failure.Specified by:
getDefaultValidator
in interfaceHasValidator<T>
Returns:
state validator
-
validate
protected void validate()Validates the current value against the constraints and sets the
invalid
property and theerrorMessage
property based on the result. If a custom error message is provided withHasValidationProperties.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
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(RadioButtonGroupI18n)
Returns:
the i18n object or
null
if no i18n object has been set -
setI18n
Sets the internationalization object for this component.
Parameters:
i18n
- the i18n object, notnull
-