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.

Solutions

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.

3 Likes

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

1 Like

The accessibility team is picking this up again as part of Djangonaut Space session 4.

Tooltip component

We’ve confirmed that for the “Changelist row sort order” pattern, a new tooltip component would be our preferred approach. It’s the only suitable option given the target user experience here (there are visual design issues with this component, but the UX seems good aside from the accessibility issues).

When we introduce this new tooltip component, we could also make use of it for “Related widget’s icon-only buttons/links” (related_widget_wrapper.html) and “Tabular inline form fields’ help text” (tabular.html), even though for those components we’d rather see an even more accessible pattern in place than a tooltip.


If anyone wants to work on this, I believe the next step for us is to confirm our accessibility requirements for a tooltip component, so we can review different implementation options (popover HTML attribute if browser and assistive tech support is sufficient, existing libraries otherwise). See ARIA - tooltip role and the Tooltip pattern in ARIA Authoring Practices Guide.

Other approaches

@erosselli will share aspects of this that feel like they close to implementation.

2 Likes

I looked into this for work some time ago, and unless I’m missing something popover isn’t enough on its own, we’d also need to wait for anchor positioning.

So we should either wait or integrate a library (or tell me I’m wrong).

I believe they’re complimentary? The Popover API means less JS and ARIA attributes needed for event handling and state management. Anchor positioning solves the visual placement. Both of which are very error-prone to reinvent but we can shop around for the right library.

Yes, just that I think we need both if we want to implement this ourselves and avoid the library shopping.

1 Like

Accessibility team has reviewed this and there’s a couple of places where the title attribute can be either removed altogether, or easily replaced by something else that’s not a tooltip. Any feedback or opinions on the following are welcome :slight_smile:

“Go” button

Django Admin “Go” button has a title that reads “Run the selected action”.

Proposed solution

We feel that the same can be achieved by simply renaming the button to “Run” instead of “Go”. It seems like many translations already took this approach, e.g some Spanish variants read “Ejecutar” (“Execute”) and French reads “Envoyer” (“Send”).

Other alternatives

We considered other alternatives, but ended up discarding them:

  • “Run the selected action” (current tooltip label): too long, would affect the layout too much, specially in smaller screens
  • “Execute” or “Submit” – not as descriptive, “Run” seems more widely used in English

“Click here to select the objects across all pages”

When selecting items in a list and clicking on the checkbox to select all items on the page, a new button appears that says “Select all number-of-items model-name”, e.g “Select all 131 tracks”.

Proposed solution

We think we should just remove this tootlip altogether, since it doesn’t provide meaningfully different information to the visible text. There is enough opportunity for confirmation of what the action does thanks to the count of selected items updating before-after clicking.

Sidebar tooltip

When hovering over one of the applications in the sidebar, you can see a title attribute that reads “Models in the {{name}} application.”

Proposed solution

We also think this should be removed, as this label doesn’t provide meaningfully different information to the visible text.

3 Likes