New pattern needed for Django admin tooltips

As part of Djangonaut Space, we’ve been tackling larger issues in the Django admin such as the ones with collapsible form sections. Another big issue we now want to fix is… inaccessible tooltips in the admin :rainbow:. There are multiple possible solutions, and we could use feedback to decide on how to prioritise them.

The problem

Admin UI components currently use the HTML title attribute to provide contextual help. For example here’s the help text to know what “Available groups” and “Chosen groups” are for / how the UI works, on my static demo of the user editing form:

Available groups and Chosen groups tooltips

First tooltip text: This is the list of available groups. You may choose some by selecting them in the box below and then clicking the "Choose" arrow between the two boxes.

For keyboard, voice recognition, and touch screen users – there is no way to access the information in the title attribute. For mouse users, it requires quite precise hand movements. Here it’s ok, but in other scenarios there isn’t always enough of a cue those tooltips are available.

The bottom line is – any use of the title attribute to provide contextual help for UI components needs a rethink.


There are a lot of possible solutions here. We don’t have to pick just the one, we can apply a different solution in different scenarios. Here are all the different design / user experience options I could think of in order of UX complexity.

Always-visible text

This is probably the simplest as far as fixing accessibility issues: move the information from the tooltips to text directly on the page, placed where appropriate. This can either replace the text or icon of the element the tooltip is on, or be positioned next to it. However most of the admin UI hasn’t been designed for widespread use of visible runs of text like this, so this would compromise on the UI’s current information density.

So this would be a great simple fix in some scenarios – and elsewhere, would be the toughest change from a design perspective – we’d potentially need to adjust the UI quite a bit to make space for this approach.

Toggle-able text

The disclosure (show/hide) pattern is a good way to display help content inline, without changing the designs as much. There would be an always-visible toggle next to the UI, and upon clicking the toggle, the information would be revealed, pushing the rest of the page down (no overlay).

Tooltip text

We’d keep the tooltip pattern, but redesign and rebuild it with accessibility considerations in mind. I think this would be the simplest change because the design wouldn’t need reinventing as much. The technical implementation would be more complex than always-visible or toggle-able text, but still reasonable.

No text

Yup. In some scenarios – we could decide to just remove the tooltip text.

Separate documentation

Finally I think it’s worth keeping in mind the point of those tooltips is to help users understand the UI. Separate documentation could do this as well, with textual descriptions and annotated screenshots. This could be within the admin still, in admindocs, or be a separate website like the developer documentation.

Other problematic tooltips

Here are other examples so people get a sense of which approach might work where.

Changelist bulk actions

On my demo changelist, there’s a tooltip on the “Go” button that says “Run the selected action”:

go button tooltip run the selected action

Changelist row sort order

Here’s another example, with a users changelist, where the user can control the order of the items with sorting controls (here, “Toggle sorting” as a tooltip on the up caret):

up caret toggle sorting for username column

There are a lot of accessibility and general usability issues with this UI element, but at least as far as label it’s really problematic that keyboard / speech recognition / touch users can’t ever know what the button is for.

Related widget’s icon-only buttons/links

This example can be seen on a Change redirect form. Here, the title serves as label for an icon-only button / link.

related widget

What next

From all of this, my personal recommendation would be to go ahead with building a new tooltip component for the admin. Though there are other options, it feels like a pattern that would work well for the admin in the long run. We’d be able to replace all existing use of title with it. Either once that’s done or as part of the process, if people deem it appropriate, we could do the more complex redesign case by case when other patterns could work better.

For now – @erosselli is interested in working on this, so we’d appreciate any feedback on how best to take this forward.


UI work is very much not my area, but I’m excited that this is being worked on!

1 Like