[Icons] Add support for <title> and <desc> elements in SVG for accessibility #2904

xDeSwa · 2025-07-11T21:57:16Z

Q	A
Bug fix?	no
New feature?	yes
Docs?	yes
Issues
License	MIT

When passing title and/or desc as attributes to ux_icon(), they are now embedded directly into the SVG as <title> and child elements.

Each <title> and element is given a unique id and automatically referenced via aria-labelledby, if no such attribute was already set.

This ensures compliance with accessibility best practices for inline SVG content.
See:

https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title

https://developer.mozilla.org/en-US/docs/Web/SVG/Element/desc

Example Usage:

{{ ux_icon('bi:plus-square-dotted', {
    width: '16px',
    height: '16px',
    class: 'text-success',
    title: 'Add Stock',
    desc: 'This icon indicates stock entry functionality.'
}) }}

Renders:

<svg class="text-success" width="16px" height="16px" aria-labelledby="icon-title-abc icon-desc-def">
    <title id="icon-title-abc">Add Stock</title>
    <desc id="icon-desc-def">This icon indicates stock entry functionality.</desc>
    <!-- inner SVG content -->
</svg>

When passing title and/or desc as attributes to ux_icon(), they are now embedded directly into the SVG as <title> and <desc> child elements. Each <title> and <desc> element is given a unique id and automatically referenced via aria-labelledby, if no such attribute was already set. This ensures compliance with accessibility best practices for inline SVG content. See: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title https://developer.mozilla.org/en-US/docs/Web/SVG/Element/desc

Kocal

Thanks for working in this!

Please be sure to add tests

src/Icons/doc/index.rst

src/Icons/src/Icon.php

Kocal · 2025-07-12T05:58:21Z

src/Icons/src/Icon.php

+            $titleId = 'title-' . bin2hex(random_bytes(4));
+            $labelledByIds[] = $titleId;
+            $a11yContent .= sprintf('<title id="%s">%s</title>', $titleId, htmlspecialchars((string) $title, ENT_QUOTES));
+        }
+
+        if ($desc) {
+            $descId = 'desc-' . bin2hex(random_bytes(4));


I feel like it's a not a good idea to generate random strings for eacg title/desc, especially when you render a lot of icons in a single page.

"IDs for the <title> and elements are generated only when the aria-labelledby attribute is automatically added to reference them."

Yeah I know, but I don't think generating random values like that is a good thing, it can be CPU intensive and it's untestable.

Instead, either we generate these ids based on the icon (name, title, description, ...), either we use an internal incremental counter or something similar

src/Icons/doc/index.rst

xDeSwa · 2025-07-12T10:39:51Z

Thanks for working in this!

Please be sure to add tests

Thanks for suggestions. can you check again please.

Kocal

I'm sorry, but I don't understand the benefits over using <title> and <desc>, instead of using aria-label and aria-description attribute. Do you have more information about that?

Tests are still missing, please make sure to add tests for making the CI green, thanks

Kocal · 2025-07-12T13:11:38Z

src/Icons/doc/index.rst

+<svg class="text-success" width="16px" height="16px" aria-labelledby="icon-title-abc icon-desc-def">
+    <title id="icon-title-abc">Add Stock</title>
+    <desc id="icon-desc-def">This icon indicates stock entry functionality.</desc>


The id attributes do no match the actual behaviour

src/Icons/src/Icon.php

Kocal · 2025-07-12T13:15:15Z

And apply Fabbot suggestions aswell, thanks

smnandre · 2025-07-15T04:21:50Z

src/Icons/doc/index.rst

+    - ``role="img"`` is **not added automatically**. You may choose to include it if your use case requires.
+    - When neither ``title``, ``desc``, ``aria-label``, nor ``aria-labelledby`` are provided, ``aria-hidden="true"`` will still be automatically applied.
+
+This feature brings UX Icons in line with modern accessibility recommendations and helps developers build more inclusive user interfaces.


I'm not so sure about that..

If an SVG is used in a context where it adds meaning to the content then it is not being used as an icon, and requires a different markup pattern

<svg role="img" focusable="false"> <title>Accessible Name</title>  </svg>

https://design-system.w3.org/styles/svg-icons.html#non-decorative-svg-accessibility

I mean, "then it is not being used as an icon" is pretty much outside the scope of this bundle.

Please correct me if i'm outdated on this :)

Also

If an element can be described by visible text, it is recommended to reference that text with an aria-labelledby attribute rather than using the <title> element.

So let's push for this recommendation no ?

smnandre · 2025-07-15T04:31:17Z

src/Icons/src/Icon.php

+
+        if ($title) {
+            if ($shouldSetLabelledBy) {
+                $titleId = 'title-' . bin2hex(random_bytes(4));


This will create unpredictable HTML

smnandre · 2025-07-15T04:34:02Z

src/Icons/src/Icon.php

+                $labelledByIds[] = $titleId;
+                $a11yContent .= sprintf('<title id="%s">%s</title>', $titleId, htmlspecialchars((string) $title, ENT_QUOTES));
+            } else {
+                $a11yContent .= sprintf('<title>%s</title>', htmlspecialchars((string) $title, ENT_QUOTES));


This will add another <title> tag in the SVG if one is already present, generating invalid markup

smnandre

I'm not really sure of the use case.. Are <title> and <desc> really something usefull for inlined SVG icons ? It does not match what i read on the topic, but i'd be happy to learn new things here.

If someone uses UX Icons to display images maybe they can add <title> and/or <desc> directly in the SVG file ?

xDeSwa added 2 commits July 12, 2025 00:50

Add support for <title> and <desc> elements in SVG for accessibility

423937e

carsonbot added Feature New Feature Status: Needs Review Needs to be reviewed labels Jul 11, 2025

Kocal requested changes Jul 12, 2025

View reviewed changes

carsonbot added Status: Needs Work Additional work is needed and removed Status: Needs Review Needs to be reviewed labels Jul 12, 2025

Kocal added the Icons label Jul 12, 2025

Kocal changed the title ~~Add support for <title> and <desc> elements in SVG for accessibility~~ [Icons] Add support for <title> and <desc> elements in SVG for accessibility Jul 12, 2025

Update for suggestions

317f732

carsonbot added Status: Needs Review Needs to be reviewed and removed Status: Needs Work Additional work is needed labels Jul 12, 2025

xDeSwa added 2 commits July 12, 2025 13:16

Update index.rst

8b8296d

Update Icon.php

27d316b

xDeSwa requested a review from Kocal July 12, 2025 10:44

Kocal requested changes Jul 12, 2025

View reviewed changes

carsonbot added Status: Needs Work Additional work is needed and removed Status: Needs Review Needs to be reviewed labels Jul 12, 2025

Merge branch 'symfony:2.x' into title-desc-feature

3dead42

carsonbot added Status: Needs Review Needs to be reviewed and removed Status: Needs Work Additional work is needed labels Jul 12, 2025

Add title/desc accessibility support and related tests

59703cf

smnandre reviewed Jul 15, 2025

View reviewed changes

Uh oh!

[Icons] Add support for <title> and <desc> elements in SVG for accessibility #2904

Are you sure you want to change the base?

[Icons] Add support for <title> and <desc> elements in SVG for accessibility #2904

Conversation

xDeSwa commented Jul 11, 2025

Uh oh!

Kocal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Kocal Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

xDeSwa Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

Kocal Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xDeSwa commented Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kocal left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kocal Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Kocal commented Jul 12, 2025

Uh oh!

smnandre Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

smnandre Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

smnandre Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

smnandre Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

smnandre left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Kocal Jul 12, 2025 •

edited

Loading

xDeSwa commented Jul 12, 2025 •

edited

Loading

Kocal left a comment •

edited

Loading