The 2026 Drupal Business Survey is open. Your response will help shape the future of the Drupal business ecosystem.Checkboxes and radios form elements can both have descriptions added to each item (or indeed other specific form properties). However, this is not documented and not widely known.
It is however covered by our tests, in FormTestCheckboxesRadiosForm:
// Expand #type checkboxes, setting custom element properties for some but not
// all options.
$form['checkboxes'] = array(
'#type' => 'checkboxes',
'#title' => 'Checkboxes',
'#options' => array(
0 => 'Zero',
'foo' => 'Foo',
1 => 'One',
'bar' => $this->t('<em>Bar - checkboxes</em>'),
'>' => "<em>Special Char</em><script>alert('checkboxes');</script>",
),
);
if ($customize) {
$form['checkboxes'] += array(
'foo' => array(
'#description' => 'Enable to foo.',
),
1 => array(
'#weight' => 10,
),
);
}
The slightly clearer way to do this is as follows:
$form['checkboxes'] = array(
'#type' => 'checkboxes',
'#title' => 'Checkboxes',
'#options' => array(
'foo' => 'Foo',
'bar' => 'Bar',
);
$form['checkboxes']['foo']['#description'] = 'description for the foo checkbox';
Documentation should be added to the Checkboxes and Radios element classes.
| Comment | File | Size | Author |
|---|---|---|---|
| #5 | interdiff-2779999-3-5.txt | 1.33 KB | shashikant_chauhan |
| #5 | 2779999-5.patch | 1.19 KB | shashikant_chauhan |
| #3 | 2779999-3.patch | 1.05 KB | shashikant_chauhan |
Issue fork drupal-2779999
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
- 2779999-document-checkboxes-and
changes, plain diff MR !1681
Comments
Comment #3
shashikant_chauhan commentedadding patch.
Comment #4
joachim commentedThanks for the patch!
Good start but needs a bit more work I think:
The descriptions should be sentences with a capital and a full stop.
I'd also add a code comment within the code example that explains it, eg:
Comment #5
shashikant_chauhan commentedThanks for the suggestion, adding updated patch.
Comment #6
David_Rothstein commentedThe patch looks good. As a small documentation improvement there is no reason this shouldn't be added to 8.2.x also, and the patch applies there as well.
Note that the corresponding issue for documenting this for the Drupal 7 form API reference is #1349432: Mention checkboxes/radios options pre-setting in forms_api_reference.html.
Comment #7
xjmRather than putting a comment within a comment in the same
@code/@endcodeblock, let's start a new one and put the comment above it. So:Looks good to me other than that. Thanks!
Comment #8
joachim commentedRe #7: taking the comment out of a code comment is a good thing, but:
this code in isolation means nothing. It only works if it's following the full radios/checkboxes definition.
Comment #9
David_Rothstein commentedI agree. It is not a new code example, but rather part of the previous one.
That said, I'd be willing to mark a patch that did it either way RTBC :)
Comment #16
dpiComment #20
guilhermevp commentedComment #22
guilhermevp commentedMade a MR based on feedback #7, but #5 still applies. Please review!
Comment #23
guilhermevp commentedComment #24
jonathanshawRTBC per #9
Comment #25
quietone commentedSetting to NW for unresolved comment.
Comment #26
joachim commented> I am concerned that both 'high_school' and 'SAT' are culturally specific and may not mean much to anyone outside of countries that have high schools and use the 'SAT' test
> Yep. In addition to all that, I checked and "SAT" is also a registered trademark, which is another reason we should probably avoid referencing it (or any similar tests).
That all seems fair enough, but isn't that all out of scope for this issue? The SAT and high school stuff is already in the example code.
I'd be happy to work on a follow-up, but I don't think the bikeshedding over what to put instead should hold up a simple docs issue which has been hanging around for 6 years.
Comment #27
lauriiiCan we open a follow-up to address the feedback from the MR?
Comment #28
joachim commentedDone: #3265929: Rewrite examples of form options to be less culturally specific.
Comment #30
dwwThis needed a trivial rebase to be merge-able. Leaving RTBC, since I didn't change any code.
Comment #34
lauriiiCommitted 46cc0e0 and pushed to 10.0.x. Also cherry-picked to 9.4.x. Thanks!
Comment #36
xjmCherry-picked to 9.3.x as a patch-release-eligible documentation improvement. Thanks!