> For the complete documentation index, see [llms.txt](https://kb.craftformswp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kb.craftformswp.com/documentation/form-building/create-form/blocks/radio-field.md).

# Radio Field

A radio button group field for CraftForms

## Overview

A complete radio input field with label and error message for CraftForms. In reality, it is a set of radio inputs. It depends how many "suboptions" you would use - it can be one or it can be many of them.

**Radio Field must be used when you want to let your users to choose ONLY ONE option. If you want to let them to choose several options - use** [**Checkboxes Field**](https://kb.craftformswp.com/documentation/form-building/create-form/blocks/checkboxes-field)**.**

![A Radio Field in a form](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2FUQJo073XHt0R9jNoHffH%2FSCR-20260902-nkqh.png?alt=media\&token=afbea27b-0e44-43e6-95db-1ba983474707)

Radio Field has several option styles (same as [Checkboxes Field](https://kb.craftformswp.com/documentation/form-building/create-form/blocks/checkboxes-field)):

* Default
* Cards
* Color Swatches
* Image Swatches
* Text Swatches

It might look like these:

![Radio Field option styles](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2FnYYRz9OrE4kA85fwhcWq%2FSCR-20260902-nkmf.png?alt=media\&token=835e08ea-265d-4170-8e35-9f93d008f978)

Choose the style in the block settings: **Options** → **Options Settings** → **Option Style**.

![Options Settings in the Radio Field block settings](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2FArVIo3ow33uT2brQUD7t%2FSCR-20260902-nlws.png?alt=media\&token=aa3ce6b9-dbfe-4ec7-afa3-b0a688d4ce3c)

Upon selecting specific displaying mode there can be additional settings for visual customisation. Example:

![Extra settings for the chosen option style](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2FEdWPcUHcgqMMTtoSn7HE%2FSCR-20260902-nmgl.png?alt=media\&token=8c52abb0-3fdd-42d8-b36e-f38e9b85ab25)

Additionally, it is possible to create options (choices) in bulk for specific displaying modes, like Image. Study this image:

![Add images from Media Library button](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2Fmlzdipe1GYiyd2zmsAgl%2FSCR-20260902-nmsv.png?alt=media\&token=d6e3dfc0-82a9-48fc-a769-0cd1cc78b009)

When Image Swatches is chosen there is an additional button **Add images from Media Library**. It opens the Media Library, where you can select several images at once. One option is created for each image. Make sure to set proper labels and other settings if used.

Option images load lazily, at the smallest image size that looks sharp in the swatch or card, so long image lists stay fast.

To fill the options from your WooCommerce products with **Generate from products…** (PRO, needs WooCommerce), see [Generate options from products](/documentation/woocommerce/generate-options-from-products.md).

## Layout Customisation

Options of the Radio Field can be displayed differently, different layout can be used. The whole Radio Field is a composite block, specifically options are grouped inside Options Group block, which a child block to Radio Field:

![Options Group block inside the Radio Field](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2FlE402vbzGxVWd3N4HycR%2FSCR-20260902-nogk.png?alt=media\&token=55e31f02-0fdf-4c41-ae03-e302cce36808)

For instance, if you want to display options horizontally, you have to:

1. Choose Options Group block
2. Set Orientation setting to Horizontal (Layout: Flex)
3. Options are displayed in a row now!

## Filter & Search

For fields with many options, like a long list of fabrics or colours, you can add a search box and filter dropdowns above the options. Visitors narrow the list down instead of scrolling through all of it. It works with every option style, in Radio Field and Checkboxes Field.

![A Radio Field with Colour and Pattern filters and a search box](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2FCYs1fkdfBXvZtmVCjamM%2Fradio-field--filter-search-front-end.jpg?alt=media)

### Turn it on

1. Select the Radio Field and open the **Filter & Search** panel in the block settings.
2. Turn on **Enable filter & search**.
3. Leave **Search box** on to show the search box. It matches the option label, value and filter values. Search is not case-sensitive and ignores accents, so "boucle" finds "Bouclé".
4. Optional: change the **Search placeholder**.
5. Click **Add filter** for each dropdown you want, like Colour or Pattern. Give it a **Filter label**. The **"All" option text** is the first entry of the dropdown, which shows every option. If you leave it empty, the filter label is used.
6. Optional: change **Max list height (px)**. The options scroll inside a box of this height. The default is 315. Enter 0 for no limit.
7. Optional: change the **No matches text**, shown when nothing matches. The default is "No matching options."

![The Filter & Search panel in the block settings](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2F9eFy8t402F3843brMrMu%2Fradio-field--filter-search-panel.jpg?alt=media)

{% hint style="info" %}
The filter key (shown under the filter label, like "Key: colour") is set from the first label you type and doesn't change afterwards. You can rename the label later without losing the values set on your options.
{% endhint %}

### Set filter values on each option

Each filter adds an input to every option. In the **Options** panel, click an option and fill in its value for each filter, like "Blue" for Colour. An option can have several values: separate them with commas, like "Blue, White".

![An option with its Colour and Pattern filter values](https://97821998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM2yV1foUgoGHBC66VBDw%2Fuploads%2Fn16aPon1rYvsjAt41Xgd%2Fradio-field--option-filter-values.jpg?alt=media)

Each dropdown lists only the values your options use. **Edit as table** keeps the filter values but doesn't show them: set them on each option.

### How it works for visitors

* Picking a value in a dropdown, or typing in the search box, hides the options that don't match.
* The option the visitor has picked always stays visible, even if it doesn't match the current filters.
* Filtering only changes what is shown. It doesn't change the field's value, conditions or validation.

The editor previews the filters too: the dropdowns and the search box work in the block, which is a quick way to find one option among hundreds while you edit.

### Per product and per catalog item `PRO`

Options can be overridden for a single WooCommerce product or catalog item, in its **Field Options** section. When a field has filters, each option there has an input for its filter value(s). With the **Merge** strategy, an overriding option keeps the form option's filter values for any filter you leave empty, so changing a price doesn't drop the option out of the filters.