Add a mechanism for accessible tooltips in core

[joedolson]

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: ​https://inclusive-components.design/tooltips-toggletips/

[oglekler]

Proposal for tooltips in settings

[oglekler]

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

References:
​https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role
​https://m2.material.io/components/tooltips#theming

[oglekler]

Here is a need for more advanced Tooltip implementation
https://core.trac.wordpress.org/ticket/21583#comment:55
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.

[davidbaumwald]

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.

[joedolson]

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.

[joedolson]

See: ​https://github.com/WordPress/gutenberg/issues/48222

[oglekler]

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?

[joedolson]

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.

[oglekler]

This could also be a tooltip: #58312

[oglekler]

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 🙏🙂

[oglekler]

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.

PR for adding the initial draft for the Tooltip functionality.

Trac ticket: https://core.trac.wordpress.org/ticket/51006

[rajinsharwar]

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.

Demo: ​https://prnt.sc/zkAl_zz_XwPo

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');

[joedolson]

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.

Adding Tooltip in Admin via only JS and CSS.

Trac ticket: https://core.trac.wordpress.org/ticket/51006

[rajinsharwar]

Updated changes: ​https://screenpal.com/watch/cZV0cIVJycu

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)​https://github.com/WordPress/wordpress-develop/pull/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.

Updated the PR based on the feedback @mukeshpanchal27 :)

[joedolson]

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.

[joedolson]

Moving this to future release. Still intend to work on for 6.7, but we feel that we won't have time for it in this release.

[oglekler]

Realted tickets: #58312 and #55343

[rajinsharwar]

Hi all, I would like to add it to the 6.7 release to get the appropriate attention to this feature. I have also made some improvements to the existing PR: 5676 ( As it was preferred to go with the PHP option to render the tooltip ). I will be adding improvements over time to this issue, also if anyone feels this is not going in the correct direction, feel free to share that!

[rajinsharwar]

As an update here's what I have done to the current tooltips.

1. Added on-hover toggle instead of on-click.
2. The toggle can be focused with the Tab key, and also unfocused with Escape.
3. The toggle is also clickable for mobile devices.
4. From the PHP function, we can now pass the $default_position, in which position we want the tooltip by default. Accepted values, "top", "bottom", "right", and "left", and default value as right.
5. The tooltip's popup will not adjust its position automatically based on screen size. For example, if the default is left, and there is space on the left, the tooltip automatically changes its position to the right.
6. If the same tooltip-id is being used to render the tooltip for duplicate elements, the tooltips still function without conflicts. ( As far as I have tested. If I have missed any, feel free to share ).
7. As each tooltip has individual IDs, extenders, or even in the core, appropriate IDs can be targeted to apply/override the styles.

Example usage:

<?php add_tooltip('tooltip-2', 'This is a Text for the Tooltip', 'Help', 'left'); ?>

<?php add_tooltip('tooltip-3', 'This is another top Text for the Tooltip', 'Helpme', 'top'); ?>

1. Added validations and _doing_it_wrong fro the arguments passed.
2. Added a new filter that can be used to change the Tooltip icon image. This is similar to the one we have in add_menu() function. We can now pass the URL, or the SVG, or the dashicon class, or even the "none" to style using CSS.

Example usage:

add_filter( 'wp_tooltip_icon', 'my_filter', 10, 2 );

function my_filter( $icon_url, $field_id ) {
    $icon_url = "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjAiIGhlaWdodD0iMjAiIHZpZXdib3g9IjAgMCAyMCAyMCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBmaWxsPSIjYTdhYWFkIiBkPSJNMTcuNiA4LjVoLTcuNXYzaDQuNGMtLjQgMi4xLTIuMyAzLjUtNC40IDMuNC0yLjYtLjEtNC42LTIuMS00LjctNC43LS4xLTIuNyAyLTUgNC43LTUuMSAxLjEgMCAyLjIuNCAzLjEgMS4ybDIuMy0yLjJDMTQuMSAyLjcgMTIuMSAyIDEwLjIgMmMtNC40IDAtOCAzLjYtOCA4czMuNiA4IDggOGM0LjYgMCA3LjctMy4yIDcuNy03LjgtLjEtLjYtLjEtMS4xLS4zLTEuN3oiIGZpbGxydWxlPSJldmVub2RkIiBjbGlwcnVsZT0iZXZlbm9kZCI+PC9wYXRoPjwvc3ZnPg==";

    return $icon_url;
}

This will show an SVG now in the tooltip.

Example:

3. Added a new action hook that's fired just before the tooltip is rendered in HTML.
4. Loading the styles and scripts for the tooltip before it's rendered to not show a slightly broken tooltip.

Screenshots:

Using Tab navigation:

[davidbaumwald]

With 6.7 Beta 1 releasing in a few hours, this is being moved to Future Release given a lack of recent momentum towards a resolution.

If any committer feels the remaining work can be resolved in time for Beta 1 or any other specific milestone and wishes to assume ownership during that cycle, feel free to update the milestone accordingly.

[joedolson]

I've worked this up, modifying PR5676 to the point where I think it's a viable option. @rajinsharwar provided a great start, but there were some things to do to enhance accessibility and make it more flexible.

I've updated the interaction model so that it matches the standards set by the US Design System: ​https://designsystem.digital.gov/components/tooltip/.

I also increased the size of the default button so that it would meet WCAG 2.5.8; the minimum size is now 26px x 26px, exceeding the minimum required of 24x24.

To make the tool more useful, I added handlers so that it can be used declaratively by adding the class '.wp-tooltip-container' to an anchor or button wrapper and a data-tooltip attribute to the control. This will improve it's flexibility for use with existing code.

For testing, use:

function test_tooltips() {
    if ( function_exists( 'add_tooltip' ) ) {
        echo '<div class="notice notice-info">';
        add_tooltip( 'Test Tooltip' );
        echo '<div class="wp-tooltip-container"><button type="button" id="wp-tooltip-custom-trigger" data-tooltip="This is the content of the tooltip">Trigger</button></div>';
        echo '</div>';
    }
}

The add_tooltip() call will test the simplest case usage of the new function; the printed code tests the declarative usage.

[swissspidy]

A bit late to the party, but just saw the notification about this.

Given that Gutenberg already maintains a tooltip component that could be easily used elsewhere in WordPress admin, it seems silly to me to maintain a completely separate implementation with a very different design and functionality. I think this is a real missed opportunity. I see that was mentioned before but never followed up on.

If a second implementation is required in the short term for whatever reason, then this should be implemented in a way that the implementation could be easily swapped out later without backward compatibility concerns, for example by making this function private and not make it available to plugins.
In such a case, I would also suggest looking at more modern web APIs that make tooltips implementations a breeze, such as Popover API and CSS anchor positioning. That means you can build accessible tooltips with basically zero JavaScript.

Besides, I would strongly advocate for a different function name. add_tooltip is too close to add_option or add_post_meta. Why not wp_print_tooltip or something?

But again, why not explore using the existing Gutenberg component first :-)

[joedolson]

I thought I'd have more time this week, and frankly, I just haven't had it. Given that I also think that using something like the popovers API in native HTML would be vastly preferable, it really makes sense to just punt this for now.

I don't personally have any interest in spending time on the Gutenberg component, and given that the popover API is really pretty close to being viable, don't think it's particularly worth while.

Different function name I'd fully support.

[SirLouen]

I'm going to be agnostic on which solution is better, either a Gutenberg implementation or an almost ready "tooltips" API.
For now, I will try to review and test this patch.

@joedolson your testing instructions are too simple:

function test_tooltips() {
    if ( function_exists( 'add_tooltip' ) ) {
        echo '<div class="notice notice-info">';
        add_tooltip( 'Test Tooltip' );
        echo '<div class="wp-tooltip-container"><button type="button" id="wp-tooltip-custom-trigger" data-tooltip="This is the content of the tooltip">Trigger</button></div>';
        echo '</div>';
    }
}

But judging by the code reviewed, there is allat more going on here.

Can @rajinsharwar or you provide full info about the "new tooltip API" to test it thoroughly?

This includes something like a use-case for the hooks provided. An example here, on how to provide a use-case to test hooks.

[SirLouen]

Updating keyword to new version

[joedolson]

Punting this again. What we'd ideally like to do is implement tooltips using native CSS popovers, but we're waiting on Firefox to complete their implementation.

It's not practical to add a custom implementation and create a permanent support burden at this time.

[joedolson]

With CSS anchor positioning having meet the basic criteria for ​WordPress browser support, let's go ahead and work on a new patch to get this resolved using native tooltips.

Trac tickets:

• https://core.trac.wordpress.org/ticket/51006 — Add a mechanism for accessible tooltips in core
• https://core.trac.wordpress.org/ticket/55343 — Add Tooltip to "Remember Me" (WP Login Form)

## Summary

#55343 needs a tooltip next to the Remember Me checkbox on wp-login.php, and the
ticket history makes it dependent on #51006 (a reusable accessible-tooltip
mechanism). This PR resolves both together:

1. Adds a small, reusable, accessible tooltip mechanism — wp_get_tooltip() plus a wp-tooltip stylesheet — built on the native Popover API + CSS anchor positioning, matching the final direction agreed in #51006.
2. Uses that mechanism to add the requested "Remember Me" tooltip on the login form, with filterable copy.

## Approach

• Native Popover API drives all interaction — open/toggle, Esc, light-dismiss, focus return — so there is no JavaScript to ship or maintain.
• CSS anchor positioning (position-area: top) places the bubble above its toggle using the popover's *implicit anchor*, so multiple tooltips on one page each anchor to their own toggle with no per-instance IDs. Gated behind @supports (anchor-name: --a).
• Visual treatment (bubble, border, shadow, bordered-triangle arrow) mirrors the existing admin pointer (wp-pointer.css).
• wp_get_tooltip( $content, $args ) returns the markup (content-first signature, mirroring wp_get_admin_notice()); the login template echoes it. Single function, return-only — the same shape as wp_required_field_indicator().
• Tooltip copy on login is filterable via login_remember_me_help_text (return '' to remove).

## Accessibility

Implements the accessible-tooltip specification from #51006 (comment #15) in full, and
targets WCAG 2.2:

• No role="tooltip", aria-haspopup, or aria-live.
• Supplemental content is associated with the trigger via aria-describedby pointing to a text-only element, so the description is the help sentence and nothing else.
• Focus does not move into the tooltip on open.
• Dismissable via Esc, click-outside, and a visible close button that returns focus to the trigger without re-opening it. Esc works in every engine.
• Close button and toggle are both 24×24 px — WCAG 2.2 2.5.8 Target Size (Minimum).
• Bubble opens above the toggle, so the focused control is never covered.
• Visible focus ring using the admin theme colour, plus a transparent outline so focus stays visible in Windows High Contrast / forced-colors mode (2.4.7).
• Plain text only, no timeout, interactive source, no title attribute.
• Triggers and labels are translatable.

## Files changed

File	Change
src/wp-includes/general-template.php	New wp_get_tooltip() — returns accessible tooltip markup.
src/wp-admin/css/wp-tooltip.css	New reusable wp-tooltip component stylesheet.
src/wp-includes/script-loader.php	Registers the wp-tooltip style and makes the login styles depend on it.
src/wp-login.php	Adds the filterable help text and renders the tooltip via wp_get_tooltip().
tests/phpunit/tests/general/wpGetTooltip.php	New unit tests for wp_get_tooltip().

## Testing instructions

1. open WordPress admin login screen /wp-login.php.
2. A ? help icon appears after "Remember Me". Click it (or focus + Enter) → tooltip opens with the security copy.
3. Dismiss via the × button, Esc, or clicking outside.
4. Keyboard: Tab to the icon → Enter opens → Esc closes and focus returns to the icon.
5. Screen reader: focusing the icon announces the button name followed by the help sentence (not the word "Close"), and the bubble is not announced as a "tooltip".
6. Developer filter:

   add_filter( 'login_remember_me_help_text', fn() => 'Custom copy.' );
      add_filter( 'login_remember_me_help_text', '__return_empty_string' ); // removes the tooltip
   

7. Unit tests: npm run test:php -- --filter Tests_General_wpGetTooltip (7 tests).

## Screenshots

Tooltip open, captured on each real engine:

Chromium:

Safari / W

ebKit :

Firefox :

---

## Use of AI Tools
AI assistance: Yes
Tool: Claude Code
Model: Opus 4.8 with 1M context
Used for: Initial code skeleton and unit tests; final implementation and tests were reviewed and edited by me.

We discussed this in the accessibility bug scrub, and what we really have a need for is both a disclosure widget helper function and a tooltip helper function. A lot of the code would be common between them, so it makes sense to implement them together.

The disclosure widget should require triggering to display the message, and the tooltip should appear on focus/hover.

It should also be possible to use them both on the same control, as an icon to trigger a help disclosure may need to have a tooltip that indicates its accessible name.

[wildworks]

As WordPress Beta1 is approaching, I would like to check the status of this ticket. Judging from ​the linked PR, it seems further discussion on the design and implementation approach is needed.

[joedolson]

@afercia and I reached agreement on intent; but it needs a review. In my opinion, it makes sense to commit it with the expectation that we can revert it or modify it if needed. It has several connected tickets that can be committed quickly as implementations.

The code is quite discrete, and would be an easy revert if that proved necessary.

But it should still get an additional review before commit.

Regarding the 'tooltip' to visually expose the accessible name, I would consider to style it like the ones used in Gutenberg: black background and #f0f0f0 text.
We could review these colors later but for now I'd consider to make them consistent.
The documentation should also make very clear that the 'tooltip' version must be exclusively used for the accessible name, and I'd consider to enforce that via code.

Clean implementation! The way you've structured this makes it easy to extend in the future. Good separation of concerns.

Accessible tooltips are surprisingly hard to get right! The approach of using aria-describedby with a visually hidden tooltip element is solid. One consideration: making sure the tooltip doesn't obscure the trigger element on small screens.

[joedolson]

There's room to enhance the test suite for this, but that can happen post-commit.

[joedolson]

In 62741:

Administration: Add function for tooltips and toggle tips.

Add functions wp_get_tooltip() and wp_get_toggletip() to support adding these popover interfaces in the core admin. wp_get_tooltip() is used as mechanism to expose accessible names when a control has focus or hover, and wp_get_toggletip() implements a popover disclosure dialog to provide extended help information.

Functions generate accessible markup, written to avoid excess verbosity for screen readers and apply best practices for voice command users as much as possible for icon-only controls.

Add an initial implementation of a toggle tip to explain the 'remember me' option on the login screen.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12212

Props joedolson, oglekler, afercia, davidbaumwald, rajinsharwar, mukesh27, swissspidy, sirlouen, rutviksavsani, wildworks, ayazahmed12, generosus, sergeybiryukov.
Fixes #51006, #55343.

[joedolson]

Will benefit from a dev note to raise awareness for extenders & educate on usage. Probably can be misc.

This is a follow-up to r62741.

Trac ticket: https://core.trac.wordpress.org/ticket/51006

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Opus 4.8
Used for: Debugging and reviewing.

Follow-up:

• ​https://github.com/WordPress/wordpress-develop/pull/12546

[westonruter]

In 62794:

Administration: Add TypeScript checking and fix TS issues in wp-tooltip.js.

The files in tsconfig.json are also re-sorted.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12546.
Follow-up to r62741.

Props westonruter, joedolson.
See #51006.

[joedolson]

In 62816:

Administration: Add tooltips for meta box utility buttons.

Meta boxes render three buttons: move up, represented by an up arrow; move down, represented with a down arrow; and show/hide, represented by a triangle pointer. These icons have clear accessible names, but no tooltips to communicate their functionality visually.

Apply the API added in [62741] to display these tooltips, and update the API so that users can pass existing button or anchor HTML into the wp_get_tooltip() function to apply tooltips to existing interface components.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12528

Props ibachal, sergeybiryukov, afercia, sabernhardt, sirlouen, joedolson, khokansardar, wildworks, adrianduffell, peterwilsoncc, jorbin, jeremyfelt.
Fixes #50921, See #51006.

[milana_cap]

Dev note published: ​https://make.wordpress.org/core/2026/08/03/introducing-name-and-informational-tool-tips-in-wordpress-7-1/