Fixed #36367 -- Improving the accessibility of the date_hierarchy layout in the admin. #19688

XChaitanyaX · 2025-07-31T05:13:26Z

Trac ticket number

ticket-36367

Branch description

Added aria label to data-hierarchy navigation for better navigation when screen readers are used.

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.

…creen readers

…reen reader

…to ticket_36367

Antoliny0919 · 2025-07-31T07:31:49Z

django/contrib/admin/templates/admin/date_hierarchy.html

-<nav class="toplinks">
+<nav class="toplinks" aria-label="Date hierarchy">


Considering translation and header navigation, I think it would be better to include an <h2> tag with visually-hidden inside and link it using aria-labelledby.

sarahboyce

Thank you for the PR 👍

I added some thoughts. The @django/accessibility team might be able to advise as to what would be the best approach

sarahboyce · 2025-07-31T07:37:31Z

django/contrib/admin/templates/admin/date_hierarchy.html

@@ -1,5 +1,5 @@
 {% if show %}
-<nav class="toplinks">
+<nav class="toplinks" aria-label="Date hierarchy">


We need to translate this, like the other nav aria-labels e.g. <nav aria-label="{% translate 'Breadcrumbs' %}">

I also think "Date hierarchy" is not the best label here, maybe "Filter by date" or "Filter by {field_name} date"
In order to make the title more descriptive, this could be determined within django.contrib.admin.templatetags.admin_list.date_hierarchy().

I also think if we create something descriptive, we may want to make this visible to all users rather than an aria-label. I don't think it is clear to anyone what these do, especially if there are multiple date fields that could be being filtered

Finally, this will need a test to be accepted 😁

Hello Sarah!
Personally, I feel that the word “hierarchy” should definitely be included, no matter what.
That’s because the links within the date hierarchy are structured in a hierarchical way.

I believe including that word could help users better understand the element when navigating through it.
Also, since it's actually possible to filter by date using the sidebar filters as well,
I think it's important to clearly distinguish between the two.

I think it’s good to add the field_name as well.
However, the real issue is that not only screen readers but also visual users cannot easily identify which field is being filtered.
Of course, we can see it from the query, but I have heard before that the admin page is no longer just a space used by developers.
This part definitely needs improvement.

I guess I personally find “hierarchy” a bit odd, maybe "filter drill-down" 🤔
But I agree it's not just a filter and so communicating that would be nice

I agree as well.
Since there is a unique structure to the hierarchy, I think users need to understand that part.
Perhaps, as you mentioned an appropriate aria-labelledby would be necessary for that.

XChaitanyaX · 2025-07-31T10:31:20Z

Thank you for reviewing,

I have some thoughts based on above comments

adding some text in the nav tag is very helpful (for visual users) as currently it has links which doesn't say anything about what they do.
and btw the text "filter by release_date" in the image is just a place holder.

in django.contrib.admin.templates.admin.date_hierarchy.html

{% load i18n %}
{% if show %}
<nav class="toplinks" aria-labelledby="date-hierarchy-label">
<span id="date-hierarchy-label">
    {% blocktrans with field_name=field_name %}Filter by {{ field_name }}{% endblocktrans %}
</span> 
... remaining code

in django.contrib.admin.templatetags.admin_list.date_hierarchy() adding "field_name": field_name in return statements. It looks like the image below.

What do you guys think? 🤔

sarahboyce · 2025-07-31T12:29:27Z

I think this is the right direction. We might play around with the wording and styling/layout but this kind of thing is what I had in mind 👍

Antoliny0919

Thank you for working on this ticket ⭐️

I like the structure you suggested.
This is just my personal opinion, but I think it would be better to structure the elements generated by the date hierarchy (links) and the tag used for the label function in a column layout.

The design aspect will probably need to be discussed with the accessibility team, but I created a simple example for reference.

And as sarah pointed out, I think testing will be necessary!

Antoliny0919 · 2025-08-03T08:25:30Z

django/contrib/admin/templates/admin/date_hierarchy.html

-<nav class="toplinks">
+<nav class="toplinks" aria-labelledby="date-hierarchy-label">
+<span id="date-hierarchy-label">
+    {% blocktrans with field_name=field_name|title %} Filter by {{ field_name }} {% endblocktrans %}


I think using blocktranslate is better than blocktrans.
Also, since verbose_name is already intended to be human readable,
I'm not sure if the title filter is really necessary 🤔

Antoliny0919 · 2025-08-03T08:53:03Z

django/contrib/admin/templates/admin/date_hierarchy.html

+<nav class="toplinks" aria-labelledby="date-hierarchy-label">
+<span id="date-hierarchy-label">
+    {% blocktrans with field_name=field_name|title %} Filter by {{ field_name }} {% endblocktrans %}
+</span> 
 {% block date-hierarchy-toplinks %}
 {% block date-hierarchy-back %}
 {% if back %}<a href="{{ back.link }}" class="date-back">&lsaquo; {{ back.title }}</a>{% endif %}


The current link elements are made up of <a> tags.
I think using a ul/li structure would be more appropriate in terms of accessibility.

Antoliny0919 · 2025-08-03T09:14:51Z

++ If you always want to get your work reviewed, please don’t forget to switch the ticket flags to off :)

XChaitanyaX · 2025-08-03T14:19:46Z

If there are more links in the hierarchy then wouldn't it be better to put them in a drop-down menu? Any thoughts on this

sarahboyce · 2025-08-06T13:14:46Z

If there are more links in the hierarchy then wouldn't it be better to put them in a drop-down menu? Any thoughts on this

I'm happy with this idea being explored. The structure is a bit like a breadcrumb drilldown filter
Below is a rough example with filesystems

Having a breadcrumb format with dropdowns means that we keep the filter not taking up very much vertical space

I don't know what the best solution is here. You might want to make a few suggestions with screenshots and start a discussion on the forum

XChaitanyaX and others added 4 commits July 31, 2025 10:37

added aria-label to date_hierarchy for better navigation when using s…

74d96a9

…creen readers

Merge branch 'django:main' into ticket_36367

2609914

removed navigation from aria-label as it is spelt twice when using sc…

5cd9a22

…reen reader

Merge branch 'ticket_36367' of github.com:XChaitanyaX/django-local in…

f68c765

…to ticket_36367

Antoliny0919 reviewed Jul 31, 2025

View reviewed changes

sarahboyce reviewed Jul 31, 2025

View reviewed changes

XChaitanyaX added 2 commits July 31, 2025 19:55

added field_name to aria-labelledby

cb71904

added field_verbose_name to display when date_hierarchy is loaded

7ea5089

XChaitanyaX force-pushed the ticket_36367 branch from 569b955 to 7ea5089 Compare July 31, 2025 14:33

XChaitanyaX requested a review from Antoliny0919 July 31, 2025 15:24

Antoliny0919 reviewed Aug 3, 2025

View reviewed changes

sarahboyce added this to django accessibility improvements Aug 5, 2025

github-project-automation bot moved this to New in django accessibility improvements Aug 5, 2025

		<nav class="toplinks">
		<nav class="toplinks" aria-label="Date hierarchy">

Uh oh!

Fixed #36367 -- Improving the accessibility of the date_hierarchy layout in the admin. #19688

Are you sure you want to change the base?

Fixed #36367 -- Improving the accessibility of the date_hierarchy layout in the admin. #19688

Uh oh!

Conversation

XChaitanyaX commented Jul 31, 2025

Trac ticket number

Branch description

Checklist

Uh oh!

Antoliny0919 Jul 31, 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!

sarahboyce left a comment

Choose a reason for hiding this comment

Uh oh!

sarahboyce Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

sarahboyce Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

sarahboyce commented Jul 31, 2025

Uh oh!

Antoliny0919 left a comment

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 Aug 3, 2025

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 Aug 3, 2025

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 commented Aug 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

XChaitanyaX commented Aug 3, 2025

Uh oh!

sarahboyce commented Aug 6, 2025

Uh oh!

Uh oh!

Antoliny0919 Jul 31, 2025 •

edited

Loading

XChaitanyaX commented Jul 31, 2025 •

edited

Loading

Antoliny0919 commented Aug 3, 2025 •

edited

Loading