Contrib.social

Separators and metadata not available to screenreaders

Open on Drupal.org →
Created on 25 June 2025, 8 days ago

Problem/motivation

Linkit can be configured to add metadata to autocomplete suggestions. It can also show results from multiple matchers at once; these are visually separated in the results. However, the metadata and separators are not read out loud when navigating the list with a screenreader. This means that screenreader users will not be able to tell whether they're linking to a node or a media item (for example), nor be able to distinguish between similarly-named results.

Steps to reproduce

Versions tested: Drupal 10.4.8; Linkit 7.0.4; Windows 11; Firefox 139; NVDA 2025.1.1

  1. Install Drupal 10.4.x with Media, and Linkit 7.0.x.
  2. Create some nodes and media items of different types. Make sure some items of each type start with the same characters.
  3. Configure a Linkit profile with two matchers, one for Content and one for Media. Add metadata such as updated date, entity bundle, or file size.
  4. Configure Linkit for CKEditor to use the profile you created.
  5. Using NVDA, navigate to the edit form for a node.
  6. Enter some text in the WYSIWYG and select it.
  7. Activate the WYSIWYG Link button.
  8. In the Linkit field, start typing characters that match the entities you created.
  9. Note that NVDA announces the number of results, and the instructions to use the arrow key to navigate.
  10. Using the arrow key, navigate to the first result.
  11. Note that the entity title is announced, but the metadata is not.
  12. Navigate down with the arrow key until you reach the separator between results from the two matchers.
  13. Note that the separator text is not announced; you don't land on it when navigating with the arrow key.

Proposed resolution

If the element containing the title of the match had an interactive role (such as a link or button), then it could take an aria-describedby attribute that would point to the metadata. This would require a unique ID on the metadata span.

This is the markup for an autocomplete match as generated by Linkit:

<li class="linkit-result-line ui-menu-item">
  <div class="linkit-result-line-wrapper published ui-menu-item-wrapper" id="ui-id-64" tabindex="-1">
    <span class="linkit-result-line--title">Home</span>
    <span class="linkit-result-line--description">Last updated June 17, 2025; Custom page</span>
  </div>
</li>

Compared to the markup generated by the core autocomplete function, as used in the Authored by field:

<li class="ui-menu-item">
  <a id="ui-id-72" tabindex="-1" class="ui-menu-item-wrapper">Site Administrator (admin)</a>
</li>

It's possible that the work in ✨ Drastically improve Drupal's default linking experience in text fields Needs work is going to affect the solution to this, but that issue hasn't landed yet and also the Linkit project description page says that adding metadata to results will remain in Linkit instead of core.

This module uses Gitlab CI for automated testing of proposed code changes. To contribute code changes, create a merge request. Patch files will not trigger automated testing and are not sufficient for review.
🐛 Bug report
Status

Active

Version

7.0

Component

Code

Created by

🇺🇸United States cboyden

Live updates comments and jobs are added and updated live.
  • Accessibility

    It affects the ability of people with disabilities or special needs (such as blindness or color-blindness) to use Drupal.

Sign in to follow issues

Merge Requests

Comments & Activities

  • Issue created by @cboyden
  • First commit to issue fork.
  • Merge request !103Issue #3532420: Separators and metadata not available to screenreaders → (Open) created by mark_fullmer
  • Comment 6 days ago →
    🇺🇸United States mark_fullmer Tucson

    Thanks for the report! The stage merge request adds a targetable unique id attribute to each autocomplete suggestion description and an aria-describedby attribute to the title. Representative output shown below:

    <div class="linkit-result-line-wrapper published ui-menu-item-wrapper" id="ui-id-8" tabindex="-1">
  <span class="linkit-result-line--title" aria-describedby="title--deb05804-034b-4f7e-a94f-70f4a7157254">test</span>
  <span class="linkit-result-line--description" id="title--deb05804-034b-4f7e-a94f-70f4a7157254">Flex Page #1 | Thu, 26 Jun 2025 - 10:08 by admin</span>
</div>
  • Comment 1 day ago →
    🇺🇸United States cboyden

    Thanks for the patch! We tested it (same setup as in the issue description) and found that NVDA did not announce the description. This is most likely because the aria-describedby attribute is added to a span tag, which has a generic role. The tag with the aria-describedby attribute needs an interactive role, such as link or button.

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024