Grouped fields
The Grouped fields component allows two closely related form inputs to be grouped together.
import { ... } from '@ag.ds-next/react/grouped-fields';Learn more about how to meet WCAG success criteria when implementing grouped fields. This makes them accessible and inclusive for users of all abilities and situations.
This component passed accessibility testing in 2022 and 2024.
Clear legend
Requirements
- Legends clearly identify the purpose of the grouped fields.
- The purpose of the grouped fields is understood and conveyed by assistive technology.
- Hint text is provided when it’s helpful.
Benefits
- Assistive technology users have equal access to legends.
- Helps all users avoid submitting an incomplete or incorrect form.
- Reduces the cognitive load for all users.
- Makes filling in forms easier for people with cognitive and learning disabilities.
- Improves understanding of available options.
- Clear headings support users with English as a second language.
WCAG references
- Understanding success criteria 2.4.2 Page titled
- Understanding success criteria 2.4.6 Headings and labels
Clear labels and instructions
Requirements
- Labels and hint text are clear and succinct.
- The purpose of the grouped field is understood and conveyed by assistive technology.
- Hint text is provided when it’s helpful.
Benefits
- Assistive technology users have equal access to labels and instructions.
- Helps all users avoid submitting an incomplete or incorrect form.
- Reduces the cognitive load for all users.
- Makes filling in forms easier for people with cognitive and learning disabilities.
- Improves understanding of available options.
- Clear labelling supports users with English as a second language.
WCAG references
- Understanding success criterion 1.3.5 Identify input purpose
- Understanding success criterion 3.3.2 Labels or instructions
Error identification
Requirements
- Input errors are detected and communicated to the user – for example, required data not entered.
- Error messages are accessible to all users, including those with disabilities.
- Error messages clearly identify the error.
- Error messages provide sufficient information for users to locate and fix the problem.
- Error messages are understood and conveyed by assistive technology.
Benefits
- Assistive technology users have equal access to error messages.
- Reduces user frustration by clearly explaining what went wrong.
- Helps users with cognitive disabilities understand and fix problems.
- Saves time by preventing repeated unsuccessful attempts.
- Enables users to solve errors themselves without having to contact tech support.
WCAG references
Error prevention
Requirements
- Hint text is provided when it’s helpful.
- Labels and hint text are clear and succinct.
- Users can check, reverse or confirm their input on forms with legal commitments, financial transactions or data modifications.
Benefits
- Clear guidance reduces anxiety about making mistakes.
- Helps users understand requirements.
- Saves time by preventing repeated incorrect input.
- Particularly valuable for users with cognitive or motor impairments.
- Provides safeguards against critical errors with significant consequences.
WCAG references
- Understanding success criterion 3.3.2 Labels or instructions
- Understanding success criterion 3.3.4 Error prevention (legal, financial, data)
Name, role, value
Requirements
- All form components have appropriate names, roles and values that are understood and conveyed by assistive technology.
- Clear label identifying the grouped field.
- ARIA roles and states where needed – for example,
aria-invalid,aria-required.
Benefits
- Assistive technology users have equal access to information on the purpose and state of the component.
- Improves usability for voice control software users.
- Helps users with cognitive challenges understand component functionality.
- Makes automation and testing more reliable.