Make WordPress Core

Opened 3 years ago

Last modified 2 weeks 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.5 Priority: normal
Severity: normal Version:
Component: General Keywords: tooltips 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 9 months ago.
Proposal for tooltips in settings

Download all attachments as: .zip

Change History (26)

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

3 years ago

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

3 years ago

#3 @afercia
3 years ago

  • Keywords tooltips added

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

3 years ago

#5 @afercia
3 years ago

  • Milestone changed from Awaiting Review to Future Release

9 months ago

Proposal for tooltips in settings

#6 @oglekler
9 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.

9 months ago

#8 @joedolson
9 months ago

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

#9 @oglekler
9 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 9 months ago by oglekler (previous) (diff)

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

7 months ago

#11 @davidbaumwald
7 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
7 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
7 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
7 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
7 months ago

This could also be a tooltip: #58312

#17 @oglekler
6 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.

4 months ago

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

4 months ago

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

3 months ago

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

3 months ago

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

3 months ago

#23 @oglekler
2 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.

2 weeks ago

  • Keywords has-patch added; needs-patch removed

PR for adding the initial draft for the Tooltip functionality.

Trac ticket:

#25 @rajinsharwar
2 weeks 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');
Note: See TracTickets for help on using tickets.