Fixed #35507 -- Improved accessibility using a search landmark and aria-labelledby. #19379

Antoliny0919 · 2025-04-13T06:17:31Z

Trac ticket number

Branch description

I have added a label to the admin search-form following the work in #18256. As suggested by MHLut, we improve accessibility by using aria-labelledby to add elements that are not visually visible but can be heard by screen reader users.

Checklist

This PR targets the main branch.
The commit message is written in past tense, mentions the ticket number, and ends with a period.
I have checked the "Has patch" ticket flag in the Trac system.
I have added or updated relevant tests.
I have added or updated relevant docs, including release notes if applicable.
I have attached screenshots in both light and dark modes for any UI changes.

thibaudcolas · 2025-04-26T10:31:05Z

Thank you @Antoliny0919! Static preview of this PR in my demo site: PR preview - Admin - Releases changelist. Can’t review just yet but changes looking reasonable. If you have the chance in the future be great for you to state in the description how exactly we’re continuing from #18256, in particular how the recommended changes there have been addressed in your new version.

cc @tut-tuuut if you can review.

Antoliny0919 · 2025-05-03T01:09:55Z

Hello @thibaudcolas 🙌 I have a question regarding accessibility.
When using Django admin pagination with a screen reader like voiceover, it currently announces the innerHTML (e.g., a page number) and the role, such as “button.”

However, I'm wondering if this information alone is sufficient for screen reader users to clearly understand what action each pagination button performs. For example, a button labeled “2” might not clearly communicate that it navigates to page 2.

Could this be considered an area for potential accessibility improvement?
(Of course, I might be misunderstanding things since I haven't used a screen reader much.)

tut-tuuut · 2025-05-03T07:07:45Z

Yes @Antoliny0919 you are right, there is room for improvement here on the paginations!

Inspiration is in W3C's and UK's design systems, what I would do in summary:

wrap the pagination in a <nav> with an accurate label provided by an aria-labelledby;
label each page link with "page x" using an aria-label or an visually hidden element;
mark the current page with aria-current="page".

tut-tuuut

Looks good to me, except for the redundant sr-only class.

tut-tuuut · 2025-05-03T07:27:15Z

django/contrib/admin/static/admin/css/base.css

+
+/* ACCESSIBILITY */
+
+.sr-only {


You don't need to add this class .sr-only, it does the same as .visually-hidden just above, which is already used in the admin.

I didn’t realize there was a class doing the same thing right above. Thank you so much tut-tuuut :)

tut-tuuut · 2025-05-03T07:29:31Z

django/contrib/admin/templates/admin/search_form.html

@@ -1,6 +1,8 @@
 {% load i18n static %}
 {% if cl.search_fields %}
-<div id="toolbar"><form id="changelist-search" method="get" role="search">
+<div id="toolbar">
+<h2 id="changelist-search-form" class="sr-only">{% blocktranslate with name=cl.opts.verbose_name_plural %}Search {{ name }}{% endblocktranslate %}</h2>


Suggested change

<h2 id="changelist-search-form" class="sr-only">{% blocktranslate with name=cl.opts.verbose_name_plural %}Search {{ name }}{% endblocktranslate %}</h2>

<h2 id="changelist-search-form" class="visually-hidden">{% blocktranslate with name=cl.opts.verbose_name_plural %}Search {{ name }}{% endblocktranslate %}</h2>

Antoliny0919 · 2025-05-04T02:37:03Z

Yes @Antoliny0919 you are right, there is room for improvement here on the paginations!

Inspiration is in W3C's and UK's design systems, what I would do in summary:
* wrap the pagination in a `<nav>` with an accurate label provided by an aria-labelledby;

* label each page link with "page x" using an aria-label or an visually hidden element;

* mark the current page with `aria-current="page"`.

Thank you for the great suggestion @tut-tuuut 💪
After incorporating the changes you recommended, I tested it with a screen reader.
When reaching the pagination area and navigating with the buttons, the following messages were announced.

Pagination Area

Pagination Button

With this change, I believe screen reader users will now be able to clearly understand when they reach the pagination area and what each button within the pagination represents.

Antoliny0919 · 2025-05-04T08:06:17Z

When accessing the area generated by date_hierarchy with a screen reader, it only announces it as “navigation.”
I believe this area also has room for accessibility improvement by using aria-labelledby to explain the purpose of the section more clearly.

It seems that there are still many parts that lack accessibility considerations.
In that sense, I feel this task requires a lot of research. 🧐

Since I’m not someone who uses a screen reader myself, there’s a chance I might not be able to fully assess whether certain parts truly have accessibility issues, even after doing some research.
For now, I’ll try to investigate as much as I can during my available time and look for areas that could benefit from accessibility improvements.

Once I’ve organized my findings, would it be okay if I request a review again? @tut-tuuut

tut-tuuut · 2025-05-04T08:14:29Z

I agree, there is a loooong way ahead of us. I think the best would be to create a lot of tiny PRs in order not to get lost in the mass of "one more thing". The accessibility of pagination could already be moved into a dedicated PR in my opinion: I have more pagination-related improvement ideas but the original PR which adds landmarks is already good.

Antoliny0919 · 2025-05-04T08:20:52Z

I agree, there is a loooong way ahead of us. I think the best would be to create a lot of tiny PRs in order not to get lost in the mass of "one more thing". The accessibility of pagination could already be moved into a dedicated PR in my opinion: I have more pagination-related improvement ideas but the original PR which adds landmarks is already good.

I agree.
In that case, I’ll move the pagination-related work to a separate PR.
Thank you so much for all your help 🥰
Would it be okay if I mention you when requesting a review related to accessibility?

tut-tuuut · 2025-05-04T08:24:12Z

Would it be okay if I mention you when requesting a review related to accessibility?

Yes please! 🥰

sarahboyce

Minor nit-picks, otherwise looks good to me!

django/contrib/admin/templatetags/admin_list.py

tests/admin_changelist/tests.py

…in the admin changelist.

sarahboyce

Thank you!

sarahboyce added selenium Apply to have Selenium tests run on a PR screenshots 🖼️ labels Apr 15, 2025

sarahboyce requested a review from a team April 15, 2025 08:30

Antoliny0919 force-pushed the ticket_35507 branch 2 times, most recently from a587d8b to 9fb562d Compare April 17, 2025 04:18

thibaudcolas added the DjangoCon Europe 🏰 label Apr 26, 2025

smithdc1 mentioned this pull request Apr 27, 2025

Ticket #35507 changed to search landmark in filter sidebar in order to improve accessibility. #18256

Closed

6 tasks

tut-tuuut reviewed May 3, 2025

View reviewed changes

Antoliny0919 force-pushed the ticket_35507 branch 2 times, most recently from 1a0e5cf to 469c694 Compare May 4, 2025 02:23

Antoliny0919 force-pushed the ticket_35507 branch from 469c694 to 484ce8e Compare May 4, 2025 12:06

sarahboyce reviewed May 13, 2025

View reviewed changes

django/contrib/admin/templatetags/admin_list.py Outdated Show resolved Hide resolved

tests/admin_changelist/tests.py Show resolved Hide resolved

Antoliny0919 force-pushed the ticket_35507 branch from 484ce8e to 2095f2d Compare May 13, 2025 22:12

Fixed #35507 -- Improved accessibility of search and filter elements …

17536c1

…in the admin changelist.

sarahboyce force-pushed the ticket_35507 branch from 2095f2d to 17536c1 Compare May 14, 2025 06:41

sarahboyce approved these changes May 14, 2025

View reviewed changes

sarahboyce merged commit 8bc3dd8 into django:main May 14, 2025
12 of 30 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fixed #35507 -- Improved accessibility using a search landmark and aria-labelledby. #19379

Fixed #35507 -- Improved accessibility using a search landmark and aria-labelledby. #19379

	<h2 id="changelist-search-form" class="sr-only">{% blocktranslate with name=cl.opts.verbose_name_plural %}Search {{ name }}{% endblocktranslate %}</h2>
	<h2 id="changelist-search-form" class="visually-hidden">{% blocktranslate with name=cl.opts.verbose_name_plural %}Search {{ name }}{% endblocktranslate %}</h2>


		/* ACCESSIBILITY */

		.sr-only {

Fixed #35507 -- Improved accessibility using a search landmark and aria-labelledby. #19379

Fixed #35507 -- Improved accessibility using a search landmark and aria-labelledby. #19379

Conversation

Trac ticket number

Branch description

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Pagination Area

Pagination Button

Choose a reason for hiding this comment

Choose a reason for hiding this comment