Fixed #36367 -- Improving the accessibility of the date_hierarchy layout in the admin. by XChaitanyaX · Pull Request #19688 · django/django

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.

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

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

+</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.

I’d agree but not sure it’s worthwhile. It would allow people to know how many items there are to navigate with, which is a plus, but not really related to other changes in this PR.

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

thibaudcolas · 2025-08-13T13:33:55Z

Static PR demo link - releases changelist. I will try to find time to test this / provide input on the forum later this week ⭐️

Antoliny0919 · 2025-08-30T12:46:52Z

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

I like this proposal. Implementing it in a breadcrumbs format would definitely improve navigation for screen readers. However, this task would essentially require rebuilding the date hierarchy component. While it is indeed an accessibility improvement through structural changes, it feels like a rather large task for me. Would it be possible to categorize this work separately?

XChaitanyaX · 2025-08-30T14:30:22Z

Any suggestions/feedback on the date hierarchy structure/remodelling please write them here.

XChaitanyaX · 2025-08-30T14:50:26Z

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

I like this proposal. Implementing it in a breadcrumbs format would definitely improve navigation for screen readers. However, this task would essentially require rebuilding the date hierarchy component. While it is indeed an accessibility improvement through structural changes, it feels like a rather large task for me. Would it be possible to categorize this work separately?

date hierarchy itself is kind of very interesting to me, the purpose is like very limited (filtering by date), the more the unique dates, the messier it gets to sort via a particular date, not mentioning the need to select the month as well and of course the day itself.
I would rather format the way the date is displayed and search via ctrl + f in the browser.

thibaudcolas

Working all as expected! Tested w/ macOS VoiceOver. Was wondering whether the label should be a heading rather than a span, but since it’s all in the same line, probably a span is good. There’s more possible improvements on the links’ markup as mentioned, but they strike me as clear "nice-to-have", while the absence of a label is way more problematic

tests/admin_changelist/test_date_hierarchy.py

jacobtylerwalls

Thank you @XChaitanyaX! I pushed minor tweaks.

Thanks @Antoliny0919, @thibaudcolas, Sarah, and space reviewers! 👾

(I plan to land soon, but Antoliny, let me know if you have any suggested tweaks to the wording, I know you were originally in favor of "hierarchy", but I think what we have is clear.)

jacobtylerwalls · 2025-12-04T20:52:45Z

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

+<span id="date-hierarchy-label">
+    {% blocktranslate %}Filter by {{ field_name }}{% endblocktranslate %}
+</span> 


Other s in the admin seem to be careful about not introducing whitespace:

Suggested change



{% blocktranslate %}Filter by {{ field_name }}{% endblocktranslate %}



{% blocktranslate %}Filter by {{ field_name }}{% endblocktranslate %}

I'll roll this in for you 👍

jacobtylerwalls · 2025-12-04T21:06:56Z

tests/admin_changelist/test_date_hierarchy.py

+        Event.objects.create(date=datetime(2017, 1, 1))
+        response = self.client.get(reverse("admin:admin_changelist_event_changelist"))
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(response, "Filter by")


I think instead of testing the template we could test that the view provided the dynamic content.

jacobtylerwalls · 2025-12-04T21:19:19Z

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

+<span id="date-hierarchy-label">
+    {% blocktranslate %}Filter by {{ field_name }}{% endblocktranslate %}
+</span> 


Looked like a slight visual misalignment here, traced to a font-size delta, assuming that was not intentional, I will add some consistency.

Thanks Sarah Boyce for the implementation idea.

Antoliny0919

(I plan to land soon, but Antoliny, let me know if you have any suggested tweaks to the wording, I know you were originally in favor of "hierarchy", but I think what we have is clear.)

Yes, I agree as well :)

Antoliny0919 reviewed Jul 31, 2025

View reviewed changes

django/contrib/admin/templates/admin/date_hierarchy.html Outdated Show resolved Hide resolved

sarahboyce reviewed Jul 31, 2025

View reviewed changes

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

thibaudcolas moved this from New to To Review in django accessibility improvements Aug 27, 2025

XChaitanyaX requested a review from Antoliny0919 October 29, 2025 14:23

thibaudcolas approved these changes Dec 4, 2025

View reviewed changes

tests/admin_changelist/test_date_hierarchy.py Outdated Show resolved Hide resolved

jacobtylerwalls approved these changes Dec 4, 2025

View reviewed changes

jacobtylerwalls force-pushed the ticket_36367 branch from 3c45292 to 92e00a9 Compare December 4, 2025 21:33

jacobtylerwalls added the screenshots 🖼️ label Dec 4, 2025

Fixed #36367 -- Added a label to the date_hierarchy in admin changelist.

dc67dbb

Thanks Sarah Boyce for the implementation idea.

jacobtylerwalls force-pushed the ticket_36367 branch from 92e00a9 to dc67dbb Compare December 4, 2025 21:36

Antoliny0919 approved these changes Dec 4, 2025

View reviewed changes

jacobtylerwalls merged commit 16252e6 into django:main Dec 5, 2025
40 checks passed

github-project-automation bot moved this from To Review to Done in django accessibility improvements Dec 5, 2025

Uh oh!

Conversation

XChaitanyaX commented Jul 31, 2025

Trac ticket number

Branch description

Checklist

Uh oh!

Uh oh!

sarahboyce left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

thibaudcolas commented Aug 13, 2025

Uh oh!

Antoliny0919 commented Aug 30, 2025

Uh oh!

XChaitanyaX commented Aug 30, 2025

Uh oh!

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

Uh oh!

Uh oh!

thibaudcolas 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!

Uh oh!

jacobtylerwalls 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

XChaitanyaX commented Jul 31, 2025 •

edited

Loading

Antoliny0919 commented Aug 3, 2025 •

edited

Loading

XChaitanyaX commented Aug 30, 2025 •

edited

Loading

thibaudcolas left a comment •

edited

Loading

jacobtylerwalls left a comment •

edited

Loading