Make WordPress Core

Opened 4 years ago

Last modified 2 months ago

#51006 accepted enhancement

Add a mechanism for accessible tooltips in core

Reported by: joedolson's profile joedolson Owned by: joedolson's profile joedolson
Milestone: 6.6 Priority: normal
Severity: normal Version:
Component: General Keywords: tooltips 2nd-opinion has-patch
Focuses: ui, accessibility, javascript Cc:


While we've worked hard to eliminate usage of the title attribute across most of WordPress core, there is still an occasional need for that type of contextual information, and the lack of it is a barrier to resolving some issues (e.g. #50921) and removing some of the last instances of the title attribute.

An accessible tooltip will need to meet these criteria:

1) Be available either via the mouse, via the keyboard, or via touch.
2) Be persistent until dismissed
3) Support primary & auxiliary usage, dependent on whether the tooltip is the sole name of the control or an elaboration of existing text.

Useful reference on accessible tooltips:

Attachments (1)

2023-03-09_09-19-53.png (23.7 KB) - added by oglekler 14 months ago.
Proposal for tooltips in settings

Download all attachments as: .zip

Change History (36)

This ticket was mentioned in Slack in #accessibility by joedolson. View the logs.

4 years ago

This ticket was mentioned in Slack in #accessibility by ryokuhi. View the logs.

4 years ago

#3 @afercia
4 years ago

  • Keywords tooltips added

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.

4 years ago

#5 @afercia
4 years ago

  • Milestone changed from Awaiting Review to Future Release

14 months ago

Proposal for tooltips in settings

#6 @oglekler
14 months ago

There are different possibilities for tooltips usage:

  • alternative to title attribute
  • standalone helper

We need them to:

  • Creating clean, more modern design in the admin and reduce visual complexity and clatter.
  • Providing unified tool to plugins and themes developers for tooltips in the admin (right now some of them have their own implementations)
  • Standardizing tooltips usage in WordPress to make sure that they are aria friendly and provide expected behavior in core, themes and plugins


This ticket was mentioned in Slack in #accessibility by joedolson. View the logs.

13 months ago

#8 @joedolson
13 months ago

  • Milestone changed from Future Release to 6.3
  • Owner set to joedolson
  • Status changed from assigned to accepted

#9 @oglekler
13 months ago

Here is a need for more advanced Tooltip implementation
and it looks like it can depend on this one's functionality.

I wonder if Tooltip in jQuery UI is good enough to cover our needs and meet all accessibility requirements, or we need to look for another solution.

Last edited 13 months ago by oglekler (previous) (diff)

This ticket was mentioned in Slack in #core by oglekler. View the logs.

12 months ago

#11 @davidbaumwald
12 months ago

I apologize if this was discussed elsewhere, but I don't see anything here. Has any consideration been given to using the Tooltip component from the block editor?

If not, I feel like this might be something that should be considered, and might be improved if there are a11y issues.

#12 @joedolson
12 months ago

The block editor tooltip doesn't seem very suitable, based on how I see it used - it's hidden from screen readers, it's not dismissable, and depends on aria-label for accessible naming.

We could work on improving that - I think it would require a pretty much total refactor. The way its used in the block editor, the only change that would be needed within that context is making it dismissable; but for broader usage, it would also need to be communicated to screen readers and not be dependent on aria-label for naming.

#14 @oglekler
12 months ago

I believe one of the requirements is an ability to use this tooltip for plugin and theme developers by adding its data in $args parameter of add_settings_field() function and possibly calling it by itself.

@davidbaumwald can we use the Tooltip component this way?

#15 @joedolson
12 months ago

Specifications for an accessible tooltip for WordPress:

Definitions: 'source' refers to the object a tooltip is related to. 'content' refers to the visible text content of the tooltip. 'name' refers to the accessible name of the control itself.

1) Tooltips are primarily supplemental information, and should not override the name of the source. This means they should not depend on something like aria-label on the source.

2) Tooltip content should not require a move of focus.

a) When the tooltip is also the name of the control, rather than supplemental information, it should be associated as a label field, either sourced from aria-label or using aria-labelledby.

b) For supplemental tooltips, the content should be associated with the source using aria-describedby. E.g. <input type="name" aria-describedby="tooltip-1"><div id="tooltip-1">Your full first and last name</div>.

3) If there is interactive content in a tooltip, it must be next in tab sequence after the source and be accessible to a screen reader or keyboard without dismissing the tooltip.

4) All tooltips must be dismissable without removing focus a source. When a tooltip appears on focus, it should be dismissable using esc. This will mean ensuring that the keyboard esc event doesn't trigger unexpected closures when used inside modals or other esc-closable contexts. It will also require a visible close button that can be used by pointer devices to close the tooltip and move focus to the source *without* re-triggering the tooltip.

a) Note: the close button will also need to meet WCAG's requirements for control size.

5) The tooltip should not use role="tooltip", aria-haspopup, or aria-live. The role has no significant support, and as written does not allow interactive content. Tooltips are not popups, and aria-live should not be used for naming and descriptions of static content.

6) Tooltips should be available for touch interactions. This ensures that a) non-hovering pointer AT will be able to get the tooltip information and b) the friction of using controls on mobile will help reduce excessive use of tooltips, since while they should be possible, they should *not* be overused.

7) Tooltips should *not* support formatting such as heading, bold text, italics, etc. These will not be conveyed to screen readers.

8) Interactive content should be strongly discouraged and avoided if at all possible. If the tooltips simply do not support it, that would be entirely adequate.

9) Tooltips should only be supported on interactive sources - buttons, links, inputs, etc.

10) The title attribute should not be used on the source.

11) There should not be a timeout on the tooltip.

#16 @oglekler
11 months ago

This could also be a tooltip: #58312

#17 @oglekler
10 months ago

  • Focuses javascript added
  • Keywords needs-patch added
  • Milestone changed from 6.3 to 6.4

This is an enhancement, and we have zero chances to make it until Beta 1, so, sadly, I am moving this ticket to 6.4.

I believe that this is a significant improvement we can make, so, I am asking all who are browsing this ticket to collaborate working on the one nice patch 🙏🙂

This ticket was mentioned in Slack in #accessibility by joedolson. View the logs.

9 months ago

This ticket was mentioned in Slack in #core by oglekler. View the logs.

8 months ago

This ticket was mentioned in Slack in #core by oglekler. View the logs.

8 months ago

This ticket was mentioned in Slack in #accessibility by joedolson. View the logs.

8 months ago

This ticket was mentioned in Slack in #accessibility by joedolson. View the logs.

7 months ago

#23 @oglekler
7 months ago

  • Milestone changed from 6.4 to 6.5

I didn't have time to work on this patch and no one picked up this so far, so I am moving this ticket into 6.5 in hope that we will make a progress there.

This ticket was mentioned in PR #5676 on WordPress/wordpress-develop by @rajinsharwar.

5 months ago

  • Keywords has-patch added; needs-patch removed

PR for adding the initial draft for the Tooltip functionality.

Trac ticket:

#25 @rajinsharwar
5 months ago

Hi all, I tried to start the work on this feature to get things started. I know the code isn't perfect or not that good, but I hope this will provide a good benchmark for getting things rolling for this feature.


Introduced a new function: add_tooltip()

It accepts a total of 3 parameters:

  • The 1st is a UNIQUE field ID, which will be used as the div ID of the tooltip container.
  • The 2nd is the tooltip-text which will be shown to the users upon click or click of Enter (For keyboard users)
  • The 3rd is an OPTIONAL parameter, which will be used as the Label for the Tooltip. If nothing passed, the default goes as "Help".

Example Usage:

add_tooltip('tooltip-1', $tagline_description);
add_tooltip('tooltip-2', 'This is a Text for the Tooltip');

#26 @joedolson
3 months ago

Thanks for getting started on this @rajinsharwar!

I'm wondering if the PHP function is necessary. I feel like this would be more easily implemented if it was done entirely in the JS, and just looked for appropriate data attribute, then generated the appropriate HTML as needed.

The JS and CSS should be something we can add to common.js and common.css, as the intended implementation should be fairly broad, and there's no intention to make this available on the front-end.

This ticket was mentioned in PR #5928 on WordPress/wordpress-develop by @rajinsharwar.

3 months ago

Adding Tooltip in Admin via only JS and CSS.

Trac ticket:

#28 @rajinsharwar
3 months ago

  • Keywords 2nd-opinion added

Updated changes:

Thanks for your feedback @joedolson, and I appreciate your suggestion. The reason I thought of going over with a function is that we can use this both in the frontend and backend. In #55343, a proposal was raised for adding a Tooltip to "Remember Me" of the wp-login.php. So, if we choose to go with only a JS approach, in that case, we might need to have it in separate files and load those both in the admin panel and in the wp-login.php. So, my opinion is to have a PHP function that can be called from both the Frontend and Admin panel and also to enqueue those scripts wherever there is a tooltip on the screen, not on all pages.

Still, if we choose to go with the JS way, and have those scripts and styles only in the admin, I have submitted the (PR 5928) as well, which includes this change :). It's now up to what we choose to go with. Requesting suggestions on this, so maybe we can try to get this land before Beta 1 in February.

Example Usage of the new PR:

<div class="tooltip-container" data-tooltip-text="<?php _e( $tooltip_description ) ?>"></div>
<div class="tooltip-container" data-tooltip-text="<?php _e( 'This is another Text for the Tooltip' ) ?>"></div>

Adding 2nd opinion for suggestions.

@rajinsharwar commented on PR #5928:

3 months ago

Updated the PR based on the feedback @mukeshpanchal27 :)

This ticket was mentioned in Slack in #accessibility by joedolson. View the logs.

3 months ago

#31 @joedolson
3 months ago

After discussing in the accessibility bug scrub, we're thinking that having the markup generated in the PHP function is more compelling. Let's pursue that further.

We'd also like to try and make use of some of the logic that already exists in the Gutenberg tooltip implementation, particularly about calculating tooltip position. This might require some coordination.

This ticket was mentioned in Slack in #core by rajinsharwar. View the logs.

3 months ago

This ticket was mentioned in Slack in #core by rajinsharwar. View the logs.

2 months ago

This ticket was mentioned in Slack in #accessibility by joedolson. View the logs.

2 months ago

#35 @swissspidy
2 months ago

  • Milestone changed from 6.5 to 6.6
Note: See TracTickets for help on using tickets.