WordPress 7.1 introduces `wp_get_tooltip()` for visible names on icon-only controls and `wp_get_toggletip()` for extended help. The helpers improve consistency, but they do not make every unlabeled control accessible automatically. The content choice, asset loading, button context, focus path, and persistent-label decision still belong to the plugin.
Use this for plugin settings, metaboxes, list tables, dashboards, login customizations, or compact administration interfaces with icon-only actions or optional explanatory help.
Quick answer
Keep persistent visible text when space permits. Use `wp_get_tooltip()` only to expose the name of an icon-only button or link, and use `wp_get_toggletip()` for longer optional help. Enqueue `wp-tooltip` JavaScript where Core does not already load it, then test keyboard, touch, zoom, focus return, Escape behavior, labels, and no-JavaScript context.
What to check first
- Inventory icon-only controls, unclear abbreviations, inline help, custom tooltip libraries, and help text hidden only by CSS.
- Choose persistent text, tooltip, toggletip, or `aria-describedby` according to whether the text is a name, instructions, or optional explanation.
- Give every generated popover a unique ID and every toggle a specific accessible label.
- Enqueue `wp-tooltip` JavaScript on custom admin or frontend screens where it is not loaded by Core.
- Test Tab, Shift+Tab, Enter, Space, Escape, touch, 200 percent zoom, screen reader announcement, focus return, and multiple open controls.
Diagnostic table
Use this table to keep the work practical. It connects the symptom to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Classify each help need | Inventory icon-only controls, unclear abbreviations, inline help, custom tooltip libraries, and help text hidden only by CSS. | Every icon-only control exposes a specific accessible name. |
| Replace only suitable controls | Choose persistent text, tooltip, toggletip, or `aria-describedby` according to whether the text is a name, instructions, or optional explanation. | Every toggletip opens and closes with keyboard, pointer, and touch. |
| Load required assets | Give every generated popover a unique ID and every toggle a specific accessible label. | Focus moves predictably and returns to the initiating control. |
| Test interaction states | Enqueue `wp-tooltip` JavaScript on custom admin or frontend screens where it is not loaded by Core. | Visible text remains the default for essential labels and instructions. |
Test scenarios to run
Run the same controlled fixture across these branches. Record the expected result before the test so a surprising response is visible immediately.
| Scenario | Fixture | Expected result |
|---|
| Icon name | Compact icon-only move action in a metabox | Tooltip exposes the specific action to pointer and keyboard users |
| Optional explanation | API-key setting needs a short security explanation | Toggletip opens, is announced, closes, and returns focus |
| Essential instruction | A field requires a format before submission | Persistent visible text remains associated with the field |
| Custom screen | Plugin admin page where Core does not preload tooltip JavaScript | Explicit enqueue produces the same tested interaction |
Why this usually happens
- A visual question-mark icon does not explain its action to assistive technology.
- A hover-only library can fail for keyboard and touch users.
- The Core stylesheet loads broadly, while the JavaScript is loaded by default only on selected screens.
Field notes
- Use plain-text content as expected by the helper.
- Verify markup remains valid when inserted inside paragraphs, table cells, and labels.
- Capture the focused element before opening and after closing the toggletip.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
echo wp_get_toggletip(
__( 'The API key is stored encrypted and can be revoked.', 'my-plugin' ),
array(
'id' => 'api-key-help',
'label' => __( 'API key help', 'my-plugin' ),
)
);
wp_enqueue_script( 'wp-tooltip' );
Safe fix order
Do the work in a sequence that makes each result easy to prove. Stop if a step produces new evidence that changes the incident scope.
- Classify each help need
- Replace only suitable controls
- Load required assets
- Test interaction states
- Remove duplicate libraries
Decision rule
Do not ship when essential instructions exist only on hover, focus becomes trapped or lost, labels are generic, content overlaps controls, or the interaction fails at keyboard and touch widths.
What to tell the client or owner
Provide the screen, control purpose, current markup, proposed helper, ID, label, enqueue path, keyboard recording, zoom screenshot, and browser results.
Production verification checklist
- Every icon-only control exposes a specific accessible name.
- Every toggletip opens and closes with keyboard, pointer, and touch.
- Focus moves predictably and returns to the initiating control.
- Visible text remains the default for essential labels and instructions.
Mistakes to avoid
- Do not replace a clear persistent label just to make the interface smaller.
- Do not use a tooltip for long instructions that users must remember while completing a field.
- Do not load a second tooltip library on the same control.
- Do not assume the script is present on every admin or frontend screen.
Questions teams ask during testing
What is the difference between tooltip and toggletip?
A tooltip makes the name of an icon-only control visible. A toggletip opens longer optional explanatory content in a dialog-like popover.
Can I pass existing button markup?
Yes. The helper can process an existing button, but verify the resulting attributes, ID, label, and event behavior.
Does the helper replace `aria-describedby`?
No. Use directly associated visible descriptions or `aria-describedby` when they fit the relationship better.
When HandL WP should help
HandL WP can inventory custom admin controls, migrate appropriate interactions to Core helpers, and verify keyboard, touch, zoom, screen reader, and browser behavior.
If this is active on a production site, test a WordPress admin accessibility change.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references