SiteLint documentation and guidelines

Checkboxes should be grouped together

Description

This rule checks that all related form controls (checkboxes or radio buttons) that share the same name attribute are visually and semantically grouped together using a <fieldset> element. When multiple checkboxes share the same name, they represent a set of related options where users can select multiple values. Without proper grouping via <fieldset>, assistive technologies cannot convey the relationship between these controls, making it difficult for users to understand that the options belong together.

Disabilities impacted

  • Visual impairments: screen reader users rely on the <fieldset> and <legend> elements to understand that a group of checkboxes or radio buttons are related. Without this grouping, each control is announced in isolation, and users may not realize that multiple options are part of a single question or category.
  • Cognitive disabilities: users with cognitive disabilities benefit from clear visual and structural grouping of related form controls. A <fieldset> provides a visual border and a logical container that helps communicate that the enclosed options belong together as a set.
  • Motor impairments: users who navigate forms via keyboard or voice commands benefit from proper grouping because it reduces cognitive load and provides clearer context for each control. Grouping helps users understand the relationship between controls without having to infer it from surrounding text.

Why it matters

When multiple checkboxes share the same name attribute, they are programmatically related—submitting the form sends multiple values under the same key. However, this programmatic relationship is not automatically conveyed to assistive technologies. The <fieldset> element explicitly groups related form controls, and the <legend> element provides a label for the entire group. This pattern is essential for creating accessible forms, especially for question sets like “Select all that apply” or multi-select preference lists. Without proper grouping, screen reader users hear a disconnected list of options without understanding their collective purpose or relationship to one another.

Coding problems and solutions

Common coding problems

  • Missing fieldset container: multiple checkboxes with the same name are placed directly in the DOM without being wrapped in a <fieldset> element.
  • Missing or empty legend: a <fieldset> exists, but it lacks a <legend> element, or the legend is empty, providing no context for the group.
  • Visual separation without semantic grouping: CSS or layout techniques (like spacing or borders) are used to visually group checkboxes, but no <fieldset> is provided for assistive technologies.
  • Separated by other content: checkboxes with the same name are scattered throughout the page rather than placed together, making it impossible to group them logically.

How to fix it

Ensure all checkboxes (or radio buttons) that share the same name attribute are contained within a <fieldset> element. Use a <legend> to describe the purpose of the group.

Correct example
<fieldset>
  <legend>Select your preferred contact methods:</legend>
  
  <label>
    <input type="checkbox" name="contact_methods" value="email">
    Email
  </label>
  
  <label>
    <input type="checkbox" name="contact_methods" value="phone">
    Phone
  </label>
  
  <label>
    <input type="checkbox" name="contact_methods" value="sms">
    SMS
  </label>
</fieldset>
Incorrect example
<!-- No grouping container -->
<div>
  <label>
    <input type="checkbox" name="contact_methods" value="email">
    Email
  </label>
  
  <label>
    <input type="checkbox" name="contact_methods" value="phone">
    Phone
  </label>
  
  <label>
    <input type="checkbox" name="contact_methods" value="sms">
    SMS
  </label>
</div>

Use fieldset for radio button groups as well

Radio buttons that share the same name also require a <fieldset> because they represent a set of mutually exclusive options.

Correct example (radio buttons)
<fieldset>
  <legend>Choose your shipping speed:</legend>
  
  <label>
    <input type="radio" name="shipping" value="standard">
    Standard (3-5 days)
  </label>
  
  <label>
    <input type="radio" name="shipping" value="expedited">
    Expedited (2-3 days)
  </label>
  
  <label>
    <input type="radio" name="shipping" value="overnight">
    Overnight (1 day)
  </label>
</fieldset>

Add proper legend text

The <legend> should be descriptive and clearly communicate what the group of options represents. Avoid generic text like “Options” or leaving the legend empty.

Correct example
<fieldset>
  <legend>Which features would you like to enable? (Select all that apply)</legend>
  <label><input type="checkbox" name="features" value="notifications"> Notifications</label>
  <label><input type="checkbox" name="features" value="backup"> Automatic backup</label>
  <label><input type="checkbox" name="features" value="analytics"> Usage analytics</label>
</fieldset>
Incorrect example (missing or empty legend)
<fieldset>
  <!-- Missing legend or empty legend -->
  <legend></legend>
  <label><input type="checkbox" name="features" value="notifications"> Notifications</label>
  <label><input type="checkbox" name="features" value="backup"> Automatic backup</label>
  <label><input type="checkbox" name="features" value="analytics"> Usage analytics</label>
</fieldset>

Nested fieldsets for complex forms

For complex forms with multiple levels of grouping, you can nest <fieldset> elements to create a hierarchical structure.

Correct example (nested fieldsets)
<fieldset>
  <legend>Communication preferences</legend>
  
  <fieldset>
    <legend>Email settings</legend>
    <label><input type="checkbox" name="email_prefs" value="newsletter"> Newsletter</label>
    <label><input type="checkbox" name="email_prefs" value="offers"> Promotional offers</label>
  </fieldset>
  
  <fieldset>
    <legend>SMS settings</legend>
    <label><input type="checkbox" name="sms_prefs" value="alerts"> Order alerts</label>
    <label><input type="checkbox" name="sms_prefs" value="promos"> Promotional SMS</label>
  </fieldset>
</fieldset>

Known Limitations

  • Single element groups: this rule only triggers when there are two or more elements sharing the same name attribute. A single checkbox or radio button with a unique name does not require a <fieldset>.
  • Dynamic groups: if checkboxes with the same name are added dynamically via JavaScript, the rule checks the DOM at analysis time. Re-validation is required after dynamic updates.
  • Hidden fields: inputs with type="hidden" or aria-hidden="true" are excluded from this rule, as they are not presented to users.
  • Cross-container grouping: this rule checks for a common <fieldset> ancestor. If related checkboxes are in different containers but still share the same name (which is semantically incorrect), the rule will report an issue. The correct solution is to either group them in one <fieldset> or use different name attributes.
  • ARIA grouping alternatives: while it is technically possible to use role="group" and aria-labelledby to create accessible groups, the <fieldset> and <legend> elements provide the most robust and widely supported solution. This rule specifically looks for <fieldset> grouping.

Resources

Rule

  • Audit: Accessibility
  • Standard: WCAG 2.1 / WCAG 2.2
  • Level: A
  • Success Criteria: 1.3.1 Info and Relationships
  • ID: group-elements-name-attribute
  • Report Message: Ensure all related form controls with name="%0" are grouped together.