Answer: Why Form.Item doesn’t add aria-describedby
In Ant Design 4.x and 5.x a Form.Item that fails validation renders an error div with role="alert", but the associated input never receives an aria-describedby attribute. This is intentional: the library expects developers to supply a help prop or to set validateStatus="error" with custom help text so that the ARIA linkage can be created automatically.
Confirmed behavior (facts)
- The error
div rendered by Form.Item has no id attribute.
- When a
help prop is provided, Ant Design generates a unique id for the help element and attaches it to the input via aria-describedby.
- Using both the default error text and a
help prop simultaneously can cause duplicate announcements.
- Neither 4.x nor 5.x releases include automatic
aria-describedby binding for the default error message.
Likely explanation (design choice)
Ant Design prioritises a lightweight API: the default error rendering is meant for visual feedback only, and the library defers accessibility concerns to the developer. Requiring an explicit help prop keeps the component flexible for custom UI patterns and avoids hard‑coding IDs that might clash in complex forms.
How to fix the issue in your form
- Provide a help prop –
<Form.Item help="Required field" rules={[{ required: true }]}>. Ant Design will automatically:
- Create a unique
id for the help div.
- Add
aria-describedby="" to the underlying input.
- Suppress the default error – If you need custom styling or markup, set
validateStatus="error" and supply help yourself. Do not rely on the library’s default error text.
- Manual binding (when using custom error components) – If you render your own error element outside of
Form.Item, add a unique id and set aria-describedby on the input manually.
- Verify with a screen reader – After adding the
help prop or manual binding, focus the input or trigger validation and confirm the error message is announced.
Avoiding duplicate announcements
Never use both the default error text and a help prop. If you need to display the error in two places (e.g., inline and in a summary), use help for the inline case and Form.ErrorList for the summary, ensuring each has a distinct id and is referenced only once by the input.
Roadmap status
Current Ant Design documentation and GitHub discussions indicate that automatic aria-describedby for the default error message is not planned for upcoming releases. The recommended approach remains the explicit help prop or manual binding.
Diagnostic question
Do you use a custom component to render error messages (e.g., a separate ErrorText component) instead of Ant Design’s default error div? This detail may affect how you implement the ARIA linkage.
antdesign