Radio Buttons

Radio button group for selecting exactly one option from a visible list with configurable vertical or horizontal layout.

Radio buttons present multiple options where users must choose exactly one. All choices are visible at once, making them ideal for short lists where the selection is mutually exclusive.

Basic Usage

Add a radio button group using the addRadio() builder method:

app/Models/Survey.php

Available Settings

Setting	Type	Description
`options`	array	Key-value pairs for radio button options
`display`	string	Layout direction: "vertical" or "horizontal" (default: vertical)
`option_source`	string	Dynamic option source (enum, model or resolver class)

Layout Options

Control how radio buttons are displayed using the display() method:

Vertical (Default)

Options stacked vertically, one per line. Best for longer labels or when space allows.

Horizontal

Options arranged in a row. Best for short labels (3-5 options) like ratings or Yes/No/Maybe.

Validation

Radio button groups are validated by the SelectFieldValidator, which ensures:

An option is selected (if field is required)
The selected value exists in the available options

Single Selection

Radio buttons allow exactly one selection. Unlike checkboxes, users cannot unselect all options once a choice is made (except by refreshing the form). If you need to allow zero selections, include a "None" or "Prefer not to answer" option.

Dynamic Options

Radio buttons support dynamic options from enums, models or custom resolvers:

Like other option-based fields, configure your option sources in config/polyform.php.

Submitted Data Format

Radio button groups submit the selected option key as a string:

 {
   "experience_level": "intermediate",
   "satisfaction": "very_satisfied"
 }

Frontend Behavior

Click radio button or label to select option
Selecting a new option automatically deselects the previous one
Tab key navigates between radio buttons
Arrow keys move selection between options
Space bar selects the focused option
Shows validation errors inline below the group

When to Use

Use Radio Buttons For:

Exactly one choice required
Short lists (2-6 options)
Mutually exclusive options
All options should be visible
Yes/No/Maybe type questions

Use Select Dropdown For:

Long lists (7+ options)
Space-constrained forms
Search/filter functionality needed
Dynamic or large option sets
Mobile-friendly compact display

List Length

Radio buttons work best with 2-6 options. For longer lists, use a Select dropdown instead. This saves space and prevents overwhelming users with too many visible choices.

Accessibility

Radio button groups use fieldset and legend elements for semantic grouping, include proper ARIA attributes and support full keyboard navigation. Screen readers announce the group label and the current selection when navigating with arrow keys.

Checkbox Group File Upload