Using the Radios Element for Single-Choice Selectionfor Drupal 11 , 10 , 9 , and 8

Where checkboxes lets a user pick any number of options, radios constrains them to exactly one — visually similar (a list of options with round selectors instead of square ones), but semantically and structurally closer to select than to checkboxes.

What you'll learn in this lesson

• The radios definition, sharing #options syntax with select and checkboxes
• Why its submitted value is a single scalar, not an array
• When to choose radios over a select dropdown for the same set of options

A basic radios element

$form['shipping'] = [
  '#type' => 'radios',
  '#title' => $this->t('Shipping method'),
  '#options' => [
    'standard' => $this->t('Standard (5-7 days)'),
    'express' => $this->t('Express (2-3 days)'),
    'overnight' => $this->t('Overnight'),
  ],
  '#default_value' => 'standard',
];

Same #options array format you've now seen twice — but #default_value here is a single key ('standard'), not an array, since only one option can ever be selected at a time.

The submitted value is a single scalar

This is where radios diverges from checkboxes: $form_state->getValue('shipping') returns exactly one key from #options — never an array, never a checked/0 structure. Functionally, it behaves like a single-select select element, just rendered differently.

switch ($form_state->getValue('shipping')) {
  case 'overnight':
    // ...
    break;
}

Radios versus select: when to use which

Both produce the exact same single-key submitted value, so the choice between them is purely about how many options there are and how visible they should be. Radios work well for a small number of options (roughly two to five) where seeing every choice at a glance genuinely helps the user decide. Beyond that, a select dropdown keeps the form visually compact — nobody wants to scroll past fifteen radio buttons to reach the submit button.

Quick check: you have exactly two options — "Yes" and "No." Would you reach for radios, checkboxes, or a single checkbox? (Either radios with two options or a single checkbox works well here — never checkboxes plural, since that's for selecting any number from a list, and a strict yes/no is a single mutually-exclusive choice, not a multi-select scenario.)

Key takeaways

• radios shares #options syntax with select and checkboxes, but its submitted value is always a single scalar key.
• #default_value on radios is one key, not an array — only one option can ever be selected.
• Prefer radios for a small, glanceable option set; prefer select once the list grows past roughly five choices.

Coming up next

You've now covered every common text and choice element. Next, we move into a genuinely different category: letting users upload actual files.