Accessibility issues with Django forms RadioSelect and CheckboxSelectMultiple

[Thibaud Colas]

In the Forms API, there are issues with the default rendering of fields that rely on widgets based on multiple radio or checkbox inputs: RadioSelect and CheckboxSelectMultiple. This is with the default rendering of those widgets, and with the custom rendering examples in the official documentation. Here is a form I set up for my testing of the default rendering:

• Live form: ​http://django-admin-tests.herokuapp.com/forms/example_form/p/
• Form fields definitions: ​https://github.com/thibaudcolas/django_admin_tests/blob/main/django_admin_tests/forms.py
• Template: ​https://github.com/thibaudcolas/django_admin_tests/blob/main/django_admin_tests/templates/django_admin_tests/example_form.html

RadioSelect issues

1. The fields aren’t semantically grouped, only visually, so the grouping isn’t apparent to assistive technlogies. It’s important that related fields are grouped, and that the group has a label attached to it. If I was auditing this professionally I would classify this as a fail for ​SC 1.3.1 - Info and Relationships of WCAG 2.1, as the grouping and label are somewhat there, just not done with the appropriate semantics.
2. Speaking of label – currently the group of fields is labeled by preceding it with <label for="id_radio_choice_required_0">Radio choice required:</label>. This overrides the label of the first field within the group (and only labels the first field, not the whole group). This is a fail for ​3.3.2: Labels or Instructions and/or SC 1.3.1.
3. Wrapping the fields each in their own list item makes the navigation more tedious, as screen readers will first announce list items numbering, and only then their content.

Here is a screenshot demonstrating the label issue with macOS VoiceOver’s rotor. Note how the first field has the wrong label due to the markup.

CheckboxSelectMultiple issues

Almost identical to the above,

• Lack of a fieldset means no semantic grouping.
• The label isn’t associated with anything for this widget, so is less problematic but no more correct.
• Wrapping the fields in list items also makes the form more verbose than it should be (and the semantics issues are the same).

Documentation issues

Additionally to the above, there are a few occurences of custom radio/checkbox markup in the documentation that will lead to the same issues:

• ​https://docs.djangoproject.com/en/3.1/ref/forms/widgets/#radioselect
• ​https://docs.djangoproject.com/en/3.1/intro/tutorial04/#write-a-minimal-form

Proposed solution

Essentially following ​technique H71 of WCAG. The ideal solution is identical for both widgets, and also for documentation code snippets:

1. Wrap the group of fields in a fieldset, including the group’s label, the inputs, the help text, and any errors.
2. Use a legend as the first item in the fieldset for the group’s label, rather than a label.
3. Replace the list markup with un-semantic div, or remove altogether. If the list markup is needed for backwards compatibility, it could also use role="presentation" so assistive technologies ignore the list & listitem semantics, but I would only recommend that as a temporary workaround.

Here is sample markup to implement the above. The div aren’t needed, I’ve only added them to preserve the vertical layout of the current implementation:

<fieldset>
    <legend>Radio choice required:</legend>
    <div><label for="id_radio_choice_required_0"><input type="radio" name="radio_choice_required" value="one" required="" id="id_radio_choice_required_0">
 One</label></div>
    <div><label for="id_radio_choice_required_1"><input type="radio" name="radio_choice_required" value="two" required="" id="id_radio_choice_required_1">
 Two</label></div>
    <div><label for="id_radio_choice_required_2"><input type="radio" name="radio_choice_required" value="three" required="" id="id_radio_choice_required_2">
 Three</label></div>
    <div><label for="id_radio_choice_required_3"><input type="radio" name="radio_choice_required" value="four" required="" id="id_radio_choice_required_3">
 Four</label></div>
    <span class="helptext">Help</span>
</fieldset>

[Thibaud Colas]

Screenshot of a RadioSelect widget, with DevTools open to see the markup, and VoiceOver rotor menu showing the Form Controls’ labels