# Form components: Option selectors

install4j BeanInfo catalog. Each entry below documents a bean class that can appear inside a `<serializedBean>` element in an install4j project file.

## Contents

- [Check box](#check-box) — `com.install4j.runtime.beans.formcomponents.CheckboxComponent`
- [Combo box](#combo-box) — `com.install4j.runtime.beans.formcomponents.ComboboxComponent`
- [Drop-down list](#drop-down-list) — `com.install4j.runtime.beans.formcomponents.DropdownListComponent`
- [List](#list) — `com.install4j.runtime.beans.formcomponents.ListComponent`
- [Radio button group](#radio-button-group) — `com.install4j.runtime.beans.formcomponents.RadiobuttonsComponent`
- [Single radio button](#single-radio-button) — `com.install4j.runtime.beans.formcomponents.SingleRadiobuttonComponent`

---

### Check box
- **Class:** `com.install4j.runtime.beans.formcomponents.CheckboxComponent`
- **Category:** Option selectors
- **Multiple instances:** yes
- **Customizer:** `com.install4j.runtime.beans.customizers.coupledcomponents.CheckboxCustomizer`

A check box with an optional leading label. The user selection (Boolean.TRUE or Boolean.FALSE) is saved to a variable.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. To configure a keyboard shortcut, prefix the mnemonic character in the label text with &, e.g."&User". The prefixed character will be underlined and the platform-specific keyboard shortcut (e.g. ALT+[character] on Windows) will allow the user to quickly navigate to this form component with the keyboard. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `requestFocus` — Request focus | boolean | User input | — | If selected, the form component will request the focus after the form is activated. If you have multiple form components in a single form that have this property selected, the result is undefined. |
| `variableName` — Variable name | String [context=variableName] (variable→ Boolean) | User input | — | The name of the variable to which the user input is assigned. The variable value will be one of Boolean.TRUE or Boolean.FALSE, depending on the user selection.The type of the variable value is java.lang.Boolean |
| `checkboxText` — Text | String | Check box | — | The text of the checkbox. Can be empty. |
| `initiallySelected` — Initially selected | boolean | Check box | — | If set, the checkbox is initially selected |
| `selectionScript` — Selection script | ScriptProperty → void | Check box | — | The script that is executed when the selection state of the component is changed by the user. The return type is void. |
| `executeSelectionScriptWhenActivated` — Also execute when screen is activated | boolean | Check box | `selectionScript` set | By default, the selection script is only shown when the selection state is changed by the user. If you select this property, the selection script is also executed each time the screen is activated. This is useful if the script manages the visibility or enablement of other form components |
| `widgetStyleId` — Toggle button widget style | String [context=widgetStyleIdOrCustom] | Check box | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `widgetStyle` — widgetStyle | ToggleButtonWidgetStyle | Check box | `widgetStyleId` (custom condition) | widgetStyle |

### Combo box
- **Class:** `com.install4j.runtime.beans.formcomponents.ComboboxComponent`
- **Category:** Option selectors
- **Multiple instances:** yes

A combo box with an optional leading label. The user can enter arbitrary text into the combo box. The user selection (the selected item as a string) is saved to a variable.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. To configure a keyboard shortcut, prefix the mnemonic character in the label text with &, e.g."&User". The prefixed character will be underlined and the platform-specific keyboard shortcut (e.g. ALT+[character] on Windows) will allow the user to quickly navigate to this form component with the keyboard. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `requestFocus` — Request focus | boolean | User input | — | If selected, the form component will request the focus after the form is activated. If you have multiple form components in a single form that have this property selected, the result is undefined. |
| `variableName` — Variable name | String [context=variableName] (variable→ String) | User input | — | The name of the variable to which the user input is assigned. The variable value will be the selected item text.The type of the variable value is java.lang.String |
| `listEntries` — Combo box entries | String[] [context=item] | Combo box | — | The items in the combo box. In the edit dialog, you have to enter one item per line. Items that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate items, this allows you to build a variable length list of items at runtime. |
| `initiallySelectedIndex` — Initially selected index | int | Combo box | — | The zero-based index of the initially selected item in the combo box.If you would like to compute this value at runtime, please set the bound variable to a java.lang.Integer value before this screen is shown. |
| `fillHorizontal` — Fill horizontal space | boolean | Combo box | — | If set, the combo box will fill all the available horizontal space, otherwise it will be as wide as required for the widest item. |
| `selectionChangedScript` — Selection change script | ScriptProperty → void | User input | — | A script that is executed when the selection is changed by the user. This script is only required for advanced customizations of the form screen. The return type is void. |
| `widgetStyleId` — Combo box widget style | String [context=widgetStyleIdOrCustom] | Combo box | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `widgetStyle` — widgetStyle | ComboBoxWidgetStyle | Combo box | `widgetStyleId` (custom condition) | widgetStyle |
| `inputVerifier` — Input validation expression | ScriptProperty → boolean | User input | — | An expression or script that validates the user input when the combo box loses the focus. If the expression returns false, the focus remains in the combo box. In that case you should display an error message. |

### Drop-down list
- **Class:** `com.install4j.runtime.beans.formcomponents.DropdownListComponent`
- **Category:** Option selectors
- **Multiple instances:** yes

A drop-down list with an optional leading label. The user selection (the selected index as a java.lang.Integer) is saved to a variable.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. To configure a keyboard shortcut, prefix the mnemonic character in the label text with &, e.g."&User". The prefixed character will be underlined and the platform-specific keyboard shortcut (e.g. ALT+[character] on Windows) will allow the user to quickly navigate to this form component with the keyboard. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `requestFocus` — Request focus | boolean | User input | — | If selected, the form component will request the focus after the form is activated. If you have multiple form components in a single form that have this property selected, the result is undefined. |
| `variableName` — Variable name | String [context=variableName] (variable→ Integer) | User input | — | The name of the variable to which the user input is assigned. The variable value will be the index of the selected item.The type of the variable value is java.lang.Integer |
| `listEntries` — Drop-down list entries | String[] [context=item] | Drop-down list | — | The items in the drop-down list. In the edit dialog, you have to enter one item per line. Items that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate items, this allows you to build a variable length list of items at runtime. |
| `initiallySelectedIndex` — Initially selected index | int | Drop-down list | — | The zero-based index of the initially selected item in the drop-down list.If you would like to compute this value at runtime, please set the bound variable to a java.lang.Integer value before this screen is shown. |
| `fillHorizontal` — Fill horizontal space | boolean | Drop-down list | — | If set, the drop-down list will fill all the available horizontal space, otherwise it will be as wide as required for the widest item. |
| `selectionChangedScript` — Selection change script | ScriptProperty → void | User input | — | A script that is executed when the selection is changed by the user. This script is only required for advanced customizations of the form screen. The return type is void. |
| `widgetStyleId` — Drop-down list widget style | String [context=widgetStyleIdOrCustom] | Drop-down list | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `widgetStyle` — widgetStyle | ComboBoxWidgetStyle | Drop-down list | `widgetStyleId` (custom condition) | widgetStyle |

### List
- **Class:** `com.install4j.runtime.beans.formcomponents.ListComponent`
- **Category:** Option selectors
- **Multiple instances:** yes

A list with an optional leading label. The user selection (the selected indices) is saved to a variable.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. To configure a keyboard shortcut, prefix the mnemonic character in the label text with &, e.g."&User". The prefixed character will be underlined and the platform-specific keyboard shortcut (e.g. ALT+[character] on Windows) will allow the user to quickly navigate to this form component with the keyboard. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `requestFocus` — Request focus | boolean | User input | — | If selected, the form component will request the focus after the form is activated. If you have multiple form components in a single form that have this property selected, the result is undefined. |
| `variableName` — Variable name | String [context=variableName] | User input | — | The name of the variable to which the user input is assigned. If multiple items can be selected, the variable value will be an int[] array with the selected indices, otherwise the variable value will be the index of the selected item as a java.lang.Integer |
| `listEntries` — List entries | String[] [context=item] | List | — | The items in the list. In the edit dialog, you have to enter one item per line. Items that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate items, this allows you to build a variable length list of items at runtime. |
| `initiallySelectedIndex` — Initially selected index | int | List | — | The zero-based index of the initially selected item in the list.If you would like to compute this value at runtime, please set the bound variable to a java.lang.Integer value before this screen is shown. |
| `fillHorizontal` — Fill horizontal space | boolean | List | — | If set, the list will fill all the available horizontal space, otherwise it will be as wide as required for the widest item. |
| `selectionChangedScript` — Selection change script | ScriptProperty → void | User input | — | A script that is executed when the selection is changed by the user. This script is only required for advanced customizations of the form screen. The return type is void. |
| `visibleRows` — Visible rows | int | List | — | If the list is scrollable, this property determines the height of the list. |
| `fillVertical` — Fill extra vertical space | boolean | List | — | If set, the form component will expand to fill remaining vertical space. Extra vertical space is only available if the form is not scrollable. Custom form screens have a "Scrollable" property, which must be set to false. |
| `scrollable` — Scrollable | boolean | List | — | If set, the list will be wrapped in a scroll pane. |
| `multiSelection` — Multi-selection | boolean | List | — | If set, the user can select multiple entries at the same time. |
| `widgetStyleId` — List widget style | String [context=widgetStyleIdOrCustom] | List | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `widgetStyle` — widgetStyle | ListWidgetStyle | List | `widgetStyleId` (custom condition) | widgetStyle |

### Radio button group
- **Class:** `com.install4j.runtime.beans.formcomponents.RadiobuttonsComponent`
- **Category:** Option selectors
- **Multiple instances:** yes

A number of radio buttons in a common button group with an optional leading label. The user selection (the selected index as a java.lang.Integer) is saved to a variable.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `variableName` — Variable name | String [context=variableName] (variable→ Integer) | User input | — | The name of the variable to which the user input is assigned. The variable value will be the index of the selected radio button.The type of the variable value is java.lang.Integer |
| `radioButtonLabels` — Radio button labels | String[] [context=label] | Radio buttons | — | The labels of all the radio buttons. In the edit dialog, you have to enter one item per line. Labels that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate labels, this allows you to build a variable length list of labels at runtime. |
| `initiallySelectedIndex` — Initially selected index | int | Radio buttons | — | The zero-based index of the initially selected radio button. If you would like to compute this value at runtime, please set the bound variable to a java.lang.Integer value before this screen is shown. |
| `axisType` — Axis | [AxisType](enums.md#axistype) | Radio buttons | — | The direction along which the radio buttons will be laid out. |
| `selectionScript` — Selection script | ScriptProperty → void | Radio buttons | — | The script that is executed when the selection state of the component is changed by the user. The return type is void. |
| `executeSelectionScriptWhenActivated` — Also execute when screen is activated | boolean | Radio buttons | `selectionScript` set | By default, the selection script is only shown when the selection state is changed by the user. If you select this property, the selection script is also executed each time the screen is activated. This is useful if the script manages the visibility or enablement of other form components |
| `widgetStyleId` — Toggle button widget style | String [context=widgetStyleIdOrCustom] | Radio buttons | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `widgetStyle` — widgetStyle | ToggleButtonWidgetStyle | Radio buttons | `widgetStyleId` (custom condition) | widgetStyle |

### Single radio button
- **Class:** `com.install4j.runtime.beans.formcomponents.SingleRadiobuttonComponent`
- **Category:** Option selectors
- **Multiple instances:** yes
- **Customizer:** `com.install4j.runtime.beans.customizers.coupledcomponents.SingleRadioButtonCustomizer`

A single radio button with an optional leading label. If selected, a specified string is saved to a variable. If you place multiple instances of this form component on a form screen and give them the same variable name, they will form a radio button group.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. To configure a keyboard shortcut, prefix the mnemonic character in the label text with &, e.g."&User". The prefixed character will be underlined and the platform-specific keyboard shortcut (e.g. ALT+[character] on Windows) will allow the user to quickly navigate to this form component with the keyboard. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `requestFocus` — Request focus | boolean | User input | — | If selected, the form component will request the focus after the form is activated. If you have multiple form components in a single form that have this property selected, the result is undefined. |
| `variableName` — Variable name | String [context=variableName] (variable→ String) | User input | — | The name of the variable to which the user input is assigned. The variable value will be the string defined in the "Variable value" property.The type of the variable value is java.lang.String |
| `radioButtonLabel` — Radio button label | String | Radio button | — | The text of the radio button. |
| `initiallySelected` — Initially selected | boolean | Radio button | — | If selected, the radio button will be initially selected. |
| `variableValue` — Variable value | String | User input | — | The value that should be written to the variable if this radio button is selected. |
| `selectionScript` — Selection script | ScriptProperty → void | Radio button | — | The script that is executed when the selection state of the component is changed by the user. The return type is void. |
| `executeSelectionScriptWhenActivated` — Also execute when screen is activated | boolean | Radio button | `selectionScript` set | By default, the selection script is only shown when the selection state is changed by the user. If you select this property, the selection script is also executed each time the screen is activated. This is useful if the script manages the visibility or enablement of other form components |
| `widgetStyleId` — Toggle button widget style | String [context=widgetStyleIdOrCustom] | Radio button | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `widgetStyle` — widgetStyle | ToggleButtonWidgetStyle | Radio button | `widgetStyleId` (custom condition) | widgetStyle |

