# Radio buttons

Use radio buttons to present a list of options from which only one item can be selected. Radio buttons are often used in forms for data entry or as a way to enable client-side filters.

{% hint style="info" %}
**Examples**

Radio button examples are available in our [Showroom](https://showroom.appfarm.app/ui-components/radio). You can view the demos, as well as access the setup in Appfarm Create. Don't have access? [Register](https://showroom.appfarm.app/sign-up).
{% endhint %}

{% tabs %}
{% tab title="Example" %}
Let us say we want to display a set of items, for instance, a set of books. Information about the books is stored in an Object Class `Books`*,* which has the following properties: `Books.Title`*,* `Books.Category`*,* `Books.Author`*,* etc. We want all of these properties displayed in a *Table or a List,* but we do not want all of the books to be shown in the same row set. Instead, we want to filter them into a few subsets, based on, for example, the `Category` property. The `Category` property should then be of an ENUM data type, containing the categories by which we are sorting our *Books*. 

In this case, we can use the **Radio Buttons** UI component, where we data-bind the **Value** property of the component to the *Category* property of our *Books* Data Source, usually over an App Variable or as a runtime Data Source property, since we only want these *Category* ENUM values to control the visibility of our subsets and be shown as our **Radio Buttons Labels.**

Once we set this right, we have to set the **Conditional Filters** in our *Table or List*, **Enable** them to filter out the subsets by these *Category* properties that are data-bound to our Radio Buttons, and set the **Filters** to display the right *Category* per each Radio Button.
{% endtab %}
{% endtabs %}

## Properties

### Selection type

Select whether to display a list of objects or a list of possible values for an object property.

* **Basic**\
  Present a list of objects in a data source. When this option is chosen you can select the data source and a property in that data source to use as a label for each option.
* **Property**\
  Display the possible values for an object property. The property must be an enum or a reference to another object class.

### Options

Select the data source that contains the objects to list.

*Not displayed when `Selection type` is `Property` and the property is an enum*.

### Display value

Select the property to use as a label for each option.

*Not displayed when `Selection type` is `Property` and the property is an enum*.

### Filter

Apply a filter to the selected data source.

*Not displayed when `Selection type` is `Property` and the property is an enum*.

### Conditional filters

Create conditional filters to apply to the selected data source.

*Not displayed when `Selection type` is `Property` and the property is an enum*.

### Value

*Displayed when `Selection type` is `Property` and the property is an enum*. 

Select the property for which to display the list of possible values. The property must be an [enum](https://docs.appfarm.io/reference/data-model/enumerated-types).

Note that if the property is within a many cardinality data source you should ensure that the options are displayed within the context of a single object, for example within an iterating container.

### **Conditional options**

*Displayed when `Selection type` is `Property` and the property is an enum*.

Create runtime conditions to restrict the displayed options. The options are evaluated as follows:

* The first condition that evaluates to true will be used, the rest are ignored.
* If no conditions are defined, all options will be displayed.
* If conditions are defined but no conditions evaluate to true, no options will be displayed.
* If enabled, the null option will always be displayed.

### **Allow null**

*Property only*. 

Enable this to add a radio button to allow the user to clear the value.

### Null label

*Property only*. 

If `Allow null` is enabled, enter a label to use for that radio button.

### Group label

Enter a descriptive label for the list of options.

### Helper text

Enter additional context about the options to help the user.

### **Auto focus**

Enable to auto focus the first option when the radio buttons are rendered.

{% hint style="info" %}
If a Radio Button with Auto Focus is outside the visible view (the viewport) when navigating to the view, the browser may scroll down to the Radio Button automatically due to the Auto Focus.
{% endhint %}

### Color

Select the color of the selected option based on the active theme.

* Primary (default)
* Secondary
* Default (this is the Secondary text color)

### Margin

Select the margin to apply to the radio button wrapper.

* Normal (default)
* Dense
* None

### Orientation

Select the display orientation of the options.

* Vertical (default)
* Horizontal

### **Hide option label**

Enable to remove the option labels.

### **Show secondary label**

*Property only. Requires vertical orientation*.

Enable a secondary label for each option containing the enum value's description from the Global Data Model.

### **Event handlers**

Enable [event handlers](https://docs.appfarm.io/reference/platform-concepts/event-handlers).

* On Value Change