[TwigBridgeRessources] add aria-invalid and aria-describedby on form inputs when validation failure exist #60902

jeanfrancois-morin · 2025-06-25T18:37:47Z

Q	A
Branch?	7.4
Bug fix?	no
New feature?	yes
Deprecations?	no
Issues
License	MIT

Context and objective

This PR aims to add the appropriate ARIA attributes (aria-invalid and aria-describedby) to form fields when validation errors are present.
The proposal is based on the recommendations of WCAG 2.1 and specifically the technique ARIA21, which describes the combined use of aria-invalid="true" and aria-describedby="<TEXT_ERROR_ID>" AFTER user input validation. It seems particularly relevant to implement this since SymfonyUX's LiveComponent allows for an auto-validation system, enabling real-time error feedback to users as they fill out the form.
Concretely, users of screen readers will be informed of the presence of errors as soon as they focus on the form field, and if an explicit error message is associated, they can access it immediately.
Note that the aria-describedby attribute can point to one or more HTML elements, allowing multiple messages (for example, a help message and an error message) to be vocalized. This PR takes this possibility into account by associating each field with the text passages _field_id_help_ and _field_id_errors_ when applicable.

Twig Side

The proposal is integrated into all form themes through the main template form_div_layout.html.twig, except for the files bootstrap_4_layout.html.twig and bootstrap_4_horizontal_layout.html.twig. In these files, errors were initially placed inside the associated label, so it is not necessary to add the aria-describedby attribute. Errors will be vocalized automatically and immediately after the label content. The aria-invalid="true" attribute remains necessary to indicate the presence of errors.

Let me know if this approach works for you, or if you would like me to modify any aspects.

carsonbot · 2025-06-25T18:37:54Z

Hey!

I see that this is your first PR. That is great! Welcome!

Symfony has a contribution guide which I suggest you to read.

In short:

Always add tests
Keep backward compatibility (see https://symfony.com/bc).
Bug fixes must be submitted against the lowest maintained branch where they apply (see https://symfony.com/releases)
Features and deprecations must be submitted against the 7.4 branch.

Review the GitHub status checks of your pull request and try to solve the reported issues. If some tests are failing, try to see if they are failing because of this change.

When two Symfony core team members approve this change, it will be merged and you will become an official Symfony contributor!
If this PR is merged in a lower version branch, it will be merged up to all maintained branches within a few days.

I am going to sit back now and wait for the reviews.

Cheers!

Carsonbot

nicolas-grekas

Looks nice to me. Can you please add a line in the changelog of the bridge, section 7.4?

jeanfrancois-morin · 2025-06-26T08:29:46Z

Hi, thanks for your feedback :)
I've made the update on the changelog. Do you want me to add more details or it's sufficient?

smnandre · 2025-07-07T21:59:04Z

src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_layout.html.twig

    {% if errors|length > 0 -%}
    {% if form is not rootform %}<span class="help-block">{% else %}<div class="alert alert-danger">{% endif %}
-    <ul class="list-unstyled">
+    <ul class="list-unstyled" id="{{ id ~ "_errors" }}">


I'm pretty sure this isn't covered by any BC policy, but... it's been considered a best practice for years in the Symfony / front-end aware community. I'm just a bit concerned this might lead to duplicate ids on the page.

So I’d recommend we communicate clearly and visibly about this (very welcome!) change—just to avoid penalizing those who were being cautious.

smnandre · 2025-07-07T21:59:24Z

src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_horizontal_layout.html.twig

+    {%- set attr = {} -%}
    {%- if help is not empty -%}
-        {%- set widget_attr = {attr: {'aria-describedby': id ~"_help"}} -%}
+        {%- set attr = attr|merge({'aria-describedby': id ~"_help"}) -%}


(same here)

smnandre · 2025-07-07T22:00:51Z

A big 👍 for the direction — we just need to be careful here, or we might end up hurting the very people who were already sensitive to this topic.

jeanfrancois-morin · 2025-07-24T17:31:07Z

Hi @smnandre, you left a review on this PR 2 weeks ago, and because there was conflicts on it since last changes on branch 7.4, I wanted to rebase it. But I think I've made a (big) mistake 🫣. So sorry, your comments are gone, and instead of 11 files changed, there's now 678 files. This is my first contrib to the framework.
Could you help me or tell me a way to fix that?
Thanks very much, and sorry again.

smnandre · 2025-07-25T02:10:15Z

bc2c2e4#r2191071092

bc2c2e4#r2191071435

TL;DR; these changes will break a lot of form integrations... I need to see once you have rebased

You did rename form blocks, right ? Or moved some attributes from place ?

If "yes" this will break a lot of websites ... :|

jeanfrancois-morin · 2025-07-25T06:31:49Z

Thanks for your quick feedback.
I didn't rename form blocks, just move the render part in a new {% block form_row_render -%}. This allow to remove many original duplicated code (like the {%- if help -%} parts) and add the common logic for help and errors attributes.

jeanfrancois-morin · 2025-07-25T06:36:06Z

And to be very precise, the rebase is done and I don't understand why I got this result of 678 files.

jeanfrancois-morin · 2025-07-25T08:17:01Z

@smnandre please forget my last message, rebase is done with a clean history now I think. Sorry for my confusion.

nicolas-grekas · 2025-09-12T15:33:18Z

Arf, tests fail because of this.

Can you please have a look?

Maybe this patch helps?

diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_horizontal_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_horizontal_layout.html.twig
index 2086c683ed2..fff657c37db 100644
--- a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_horizontal_layout.html.twig
+++ b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_horizontal_layout.html.twig
@@ -23,6 +23,25 @@
 
 {# Rows #}
 
+{% block form_row -%}
+    {%- set attr = {} -%}
+    {%- set aria_describedby = [] -%}
+    {%- if help -%}
+        {%- set aria_describedby = aria_describedby|merge([id ~ "_help"]) -%}
+    {%- endif -%}
+    {%- if errors|length > 0 -%}
+        {%- set aria_describedby = aria_describedby|merge([id ~ "_errors"]) -%}
+    {%- endif -%}
+    {%- if aria_describedby|length > 0 -%}
+        {%- set attr = attr|merge({'aria-describedby': aria_describedby|join(' ')}) -%}
+    {%- endif -%}
+    {%- if errors|length > 0 -%}
+        {%- set attr = attr|merge({'aria-invalid': 'true'}) -%}
+    {%- endif -%}
+    {%- set widget_attr = {attr: attr} -%}
+    {{- block('form_row_render') -}}
+{%- endblock form_row %}
+
 {% block form_row_render -%}
     {%- if expanded is defined and expanded -%}
         {{ block('fieldset_form_row') }}
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_layout.html.twig
index 5e5abc03c15..32d006b01ea 100644
--- a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_layout.html.twig
+++ b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_layout.html.twig
@@ -320,6 +320,25 @@
 
 {# Rows #}
 
+{%- block form_row -%}
+    {%- set attr = {} -%}
+    {%- set aria_describedby = [] -%}
+    {%- if help -%}
+        {%- set aria_describedby = aria_describedby|merge([id ~ "_help"]) -%}
+    {%- endif -%}
+    {%- if errors|length > 0 -%}
+        {%- set aria_describedby = aria_describedby|merge([id ~ "_errors"]) -%}
+    {%- endif -%}
+    {%- if aria_describedby|length > 0 -%}
+        {%- set attr = attr|merge({'aria-describedby': aria_describedby|join(' ')}) -%}
+    {%- endif -%}
+    {%- if errors|length > 0 -%}
+        {%- set attr = attr|merge({'aria-invalid': 'true'}) -%}
+    {%- endif -%}
+    {%- set widget_attr = {attr: attr} -%}
+    {{- block('form_row_render') -}}
+{%- endblock form_row %}
+
 {%- block form_row_render -%}
     {%- if compound is defined and compound -%}
         {%- set element = 'fieldset' -%}
diff --git a/src/Symfony/Bridge/Twig/Tests/Extension/AbstractBootstrap5HorizontalLayoutTestCase.php b/src/Symfony/Bridge/Twig/Tests/Extension/AbstractBootstrap5HorizontalLayoutTestCase.php
index 1c02f9e1020..7fdafec95b2 100644
--- a/src/Symfony/Bridge/Twig/Tests/Extension/AbstractBootstrap5HorizontalLayoutTestCase.php
+++ b/src/Symfony/Bridge/Twig/Tests/Extension/AbstractBootstrap5HorizontalLayoutTestCase.php
@@ -43,9 +43,11 @@ abstract class AbstractBootstrap5HorizontalLayoutTestCase extends AbstractBootst
             [@class="col-sm-10"]
             [
                 ./input[@id="name"]
-                /following-sibling::div
-                    [@class="invalid-feedback d-block"]
-                    [.="[trans]Error![/trans]"]
+                /following-sibling::div[@id="name_errors"]
+                    [
+                        ./div[@class="invalid-feedback d-block"]
+                        [.="[trans]Error![/trans]"]
+                    ]
             ]
             [count(./div)=1]
     ]
@@ -74,9 +76,11 @@ abstract class AbstractBootstrap5HorizontalLayoutTestCase extends AbstractBootst
             [@class="col-sm-10"]
             [
                 ./input[@id="name"]
-                /following-sibling::div
-                    [@class="invalid-feedback d-block"]
-                    [.="[trans]Error![/trans]"]
+                /following-sibling::div[@id="name_errors"]
+                    [
+                        ./div[@class="invalid-feedback d-block"]
+                        [.="[trans]Error![/trans]"]
+                    ]
             ]
             [count(./div)=1]
     ]
diff --git a/src/Symfony/Bridge/Twig/Tests/Extension/AbstractBootstrap5LayoutTestCase.php b/src/Symfony/Bridge/Twig/Tests/Extension/AbstractBootstrap5LayoutTestCase.php
index 4b3aa7fa5eb..780beaddc56 100644
--- a/src/Symfony/Bridge/Twig/Tests/Extension/AbstractBootstrap5LayoutTestCase.php
+++ b/src/Symfony/Bridge/Twig/Tests/Extension/AbstractBootstrap5LayoutTestCase.php
@@ -50,9 +50,11 @@ abstract class AbstractBootstrap5LayoutTestCase extends AbstractBootstrap4Layout
     [
         ./label[@for="name"]
         /following-sibling::input[@id="name"]
-        /following-sibling::div
-            [@class="invalid-feedback d-block"]
-            [.="[trans]Error![/trans]"]
+        /following-sibling::div[@id="name_errors"]
+            [
+                ./div[@class="invalid-feedback d-block"]
+                [.="[trans]Error![/trans]"]
+            ]
     ]
     [count(./div)=1]
 '
@@ -75,9 +77,11 @@ abstract class AbstractBootstrap5LayoutTestCase extends AbstractBootstrap4Layout
     [
         ./label[@for="name"]
         /following-sibling::input[@id="name"]
-        /following-sibling::div
-            [@class="invalid-feedback d-block"]
-            [.="[trans]Error![/trans]"]
+        /following-sibling::div[@id="name_errors"]
+            [
+                ./div[@class="invalid-feedback d-block"]
+                [.="[trans]Error![/trans]"]
+            ]
     ]
     [count(./div)=1]
 '
@@ -320,12 +324,13 @@ abstract class AbstractBootstrap5LayoutTestCase extends AbstractBootstrap4Layout
         $html = $this->renderErrors($form->createView());
 
         $this->assertMatchesXpath($html,
-            '/div
-    [@class="alert alert-danger d-block"]
-    [.="[trans]Error 1[/trans]"]
-    /following-sibling::div
-    [@class="alert alert-danger d-block"]
-    [.="[trans]Error 2[/trans]"]
+            '/div[@id="_errors"]
+    [
+        ./div[@class="alert alert-danger d-block"]
+        [.="[trans]Error 1[/trans]"]
+        /following-sibling::div[@class="alert alert-danger d-block"]
+        [.="[trans]Error 2[/trans]"]
+    ]
 '
         );
     }
@@ -338,12 +343,13 @@ abstract class AbstractBootstrap5LayoutTestCase extends AbstractBootstrap4Layout
         $html = $this->renderErrors($form->get('name')->createView());
 
         $this->assertMatchesXpath($html,
-            '/div
-    [@class="invalid-feedback d-block"]
-    [.="[trans]Error 1[/trans]"]
-    /following-sibling::div
-    [@class="invalid-feedback d-block"]
-    [.="[trans]Error 2[/trans]"]
+            '/div[@id="name_errors"]
+    [
+        ./div[@class="invalid-feedback d-block"]
+        [.="[trans]Error 1[/trans]"]
+        /following-sibling::div[@class="invalid-feedback d-block"]
+        [.="[trans]Error 2[/trans]"]
+    ]
 '
         );
     }

tests fail

jeanfrancois-morin · 2025-09-18T18:30:08Z

Hi,
Tests look ok now by removing errors wrapper (I added) and adding individual error IDs for each message in bootstrap_5 templates.
I report this on other templates for better maintainability.
Let me know if you have suggestions for improvement.
Cheers

…inputs when validation failure exist

fabpot · 2025-09-24T07:02:52Z

Thank you @jeanfrancois-morin.

carsonbot added Status: Needs Review Feature labels Jun 25, 2025

carsonbot added this to the 7.4 milestone Jun 25, 2025

nicolas-grekas reviewed Jun 26, 2025

View reviewed changes

smnandre reviewed Jul 7, 2025

View reviewed changes

jeanfrancois-morin requested review from OskarStark, chalasr, dunglas, jderusse, kbond, lyrixx, welcoMattic, xabbuh and yceruto as code owners July 24, 2025 17:15

jeanfrancois-morin force-pushed the form-widget-aria-attibutes branch from b8d1c4c to d9ca05c Compare July 25, 2025 08:09

jeanfrancois-morin force-pushed the form-widget-aria-attibutes branch from d9ca05c to ed88b5c Compare September 12, 2025 07:12

nicolas-grekas previously approved these changes Sep 12, 2025

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Review labels Sep 12, 2025

jeanfrancois-morin force-pushed the form-widget-aria-attibutes branch 3 times, most recently from 4df56ab to d5cafa2 Compare September 18, 2025 18:17

fabpot approved these changes Sep 24, 2025

View reviewed changes

[TwigBridgeRessources] add aria-invalid and aria-describedby on form …

6957eba

…inputs when validation failure exist

fabpot force-pushed the form-widget-aria-attibutes branch from d5cafa2 to 6957eba Compare September 24, 2025 07:02

fabpot merged commit 871b5b2 into symfony:7.4 Sep 24, 2025
11 of 13 checks passed

fabpot mentioned this pull request Sep 24, 2025

[TwigBridgeRessources] add aria-invalid and aria-describedby on form in… symfony/symfony-docs#21405

Closed

This was referenced Oct 27, 2025

Release v7.4.0-BETA1 #62172

Merged

Release v8.0.0-BETA1 #62173

Merged

Uh oh!

[TwigBridgeRessources] add aria-invalid and aria-describedby on form inputs when validation failure exist #60902

[TwigBridgeRessources] add aria-invalid and aria-describedby on form inputs when validation failure exist #60902

Uh oh!

Conversation

jeanfrancois-morin commented Jun 25, 2025

Context and objective

Twig Side

Uh oh!

carsonbot commented Jun 25, 2025

Uh oh!

nicolas-grekas left a comment

Choose a reason for hiding this comment

Uh oh!

jeanfrancois-morin commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

smnandre Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

smnandre Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

smnandre Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

smnandre Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

smnandre commented Jul 7, 2025

Uh oh!

jeanfrancois-morin commented Jul 24, 2025

Uh oh!

smnandre commented Jul 25, 2025

Uh oh!

jeanfrancois-morin commented Jul 25, 2025

Uh oh!

jeanfrancois-morin commented Jul 25, 2025

Uh oh!

jeanfrancois-morin commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nicolas-grekas commented Sep 12, 2025

Uh oh!

jeanfrancois-morin commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fabpot commented Sep 24, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jeanfrancois-morin commented Jun 26, 2025 •

edited

Loading

jeanfrancois-morin commented Jul 25, 2025 •

edited

Loading

jeanfrancois-morin commented Sep 18, 2025 •

edited

Loading