vaadin-framework/documentation/components/components-optiongroups.asciidoc

---
title: CheckBoxGroup and RadioButtonGroup
order: 19
layout: page
---

[[components.optiongroups]]
= CheckBoxGroup and RadioButtonGroup

ifdef::web[]
[.sampler]
image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/multiple-value/option-group"]
endif::web[]

[classname]#RadioButtonGroup# is a single selection component that allows 
selection from a group of radio buttons. [classname]#CheckBoxGroup# is a multiselection
component where items are displayed as check boxes. The common selection component features are
described in
<<dummy/../../../framework/components/components-selection#components.selection,"Selection Components">>.

[[figure.components.optiongroups]]
.RadioButtonGroup and CheckBoxGroup
image::img/optiongroup-basic.png[width=45%, scaledwidth=70%]

[source, java]
----
// A single-select radio button group
RadioButtonGroup<String> single =
    new RadioButtonGroup<>("Single Selection");
single.setItems("Single", "Sola", "Yksi");

// A multi-select check box group
CheckBoxGroup<String> multi =
    new CheckBoxGroup<>("Multiple Selection");
multi.setItems("Many", "Muchos", "Monta");
----

<<figure.components.optiongroups>> shows the [classname]#RadioButtonGroup#  and 
[classname]#CheckBoxGroup#.

You can also create check boxes individually using the [classname]#CheckBox#
class, as described in
<<dummy/../../../framework/components/components-checkbox#components.checkbox,"CheckBox">>.
The advantages of the [classname]#CheckBoxGroup# component are that as it
maintains the individual check box objects, you can get an array of the
currently selected items easily, and that you can easily change the appearance
of a single component and use it with a [classname]#Binder#.

[[components.optiongroups.disabling]]
== Disabling Items

You can disable individual items in a [classname]#RadioButtonGroup# or a [classname]#CheckBoxGroup# with
[methodname]#setItemEnabledProvider()#. The user can not select or deselect disabled
items in a [classname]#CheckBoxGroup#, but in a [classname]#RadioButtonGroup# the user can change the
selection from a disabled to an enabled item. The selections can be changed
programmatically regardless of whether an item is enabled or disabled.

[source, java]
----
// Have a radio button group with some items
RadioButtonGroup<String> group = new RadioButtonGroup<>("My Disabled Group");
group.setItems("One", "Two", "Three");

// Disable one item
group.setItemEnabledProvider(item-> !"Two".equals(item));
----

[[figure.components.optiongroups.disabling]]
.[classname]#RadioButtonGroup# with a Disabled Item
image::img/optiongroup-disabling.png[width=25%, scaledwidth=50%]

Setting an item as disabled turns on the [literal]#++v-disabled++# style for it.

[[components.optiongroups.css]]
== CSS Style Rules


[source, css]
----
.v-select-optiongroup {}
  .v-select-option.v-checkbox {}
  .v-select-option.v-radiobutton {}
----

The [literal]#++v-select-optiongroup++# is the overall style for the component.
Each check box will have the [literal]#++v-checkbox++# style, borrowed from the
[classname]#CheckBox# component, and each radio button the
[literal]#++v-radiobutton++# style. Both the radio buttons and check boxes will
also have the [literal]#++v-select-option++# style that allows styling
regardless of the option type. Disabled items have additionally the
[literal]#++v-disabled++# style.


[[components.optiongroups.css.horizontal]]
=== Horizontal Layout

The options are normally laid out vertically. You can switch to horizontal layout by using the style name [parameter]#ValoTheme.OPTIONGROUP_HORIZONTAL# with [methodname]#addStyleName()#.