WordPress 7.1 introduces an accessible tooltip mechanism and applies it across Core and the block editor. Plugins that wrap Core controls, copy internal markup, inject their own title attributes, or build custom disabled buttons can produce duplicate names, silent icons, hover-only instructions, or focus traps after the update. The test must inspect both the visual tooltip and the accessibility tree.
Use this for plugin authors, agencies with custom wp-admin screens, block libraries, editorial tools, WooCommerce extensions, and sites with icon-only toolbar actions.
Quick answer
Inventory icon-only and compact controls, then test each with mouse, keyboard, touch emulation, high zoom, and a screen reader. The control needs a concise accessible name without relying on hover. The tooltip should appear on the intended input modes, include shortcut information when useful, avoid covering the target, close predictably, and not duplicate the name announced by assistive technology.
What to check first
- List custom toolbar, sidebar, modal, list-table, metabox, settings, and block controls that use icons or title attributes.
- Capture role, accessible name, description, shortcut, disabled state, focus order, and visible tooltip text before and after WordPress 7.1.
- Test pointer hover, keyboard focus, Escape, zoom, narrow viewport, high contrast, and at least one screen reader.
- Inspect controls created dynamically after AJAX navigation, block insertion, modal opening, and plugin state changes.
- Separate a Core regression from invalid plugin markup by reproducing with the plugin disabled or a minimal test control.
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Give every control a stable semantic role and concise accessible name. | List custom toolbar, sidebar, modal, list-table, metabox, settings, and block controls that use icons or title attributes. | Icon-only controls have one correct accessible name. |
| Remove duplicate title, aria-label, or description sources after checking the accessibility tree. | Capture role, accessible name, description, shortcut, disabled state, focus order, and visible tooltip text before and after WordPress 7.1. | Tooltips appear and close predictably for supported input modes. |
| Adopt the supported WordPress tooltip mechanism where it fits the plugin architecture. | Test pointer hover, keyboard focus, Escape, zoom, narrow viewport, high contrast, and at least one screen reader. | Shortcut text is visible and understandable without changing the command name. |
| Repair overlay positioning, focus handling, translated text, and dynamic initialization. | Inspect controls created dynamically after AJAX navigation, block insertion, modal opening, and plugin state changes. | No plugin control loses focus, clips essential text, or initializes duplicate overlays. |
Why this usually happens
- A title attribute and an explicit accessible label can create redundant announcements.
- A copied Core component may depend on private markup that changed with the new mechanism.
- Portals and overlays can be clipped, detached from their control, or placed under another admin layer.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
control,role,name,tooltip,shortcut,keyboard,screen_reader
insert-block,button,Insert block,Insert block,Ctrl+Alt+B,pass,pass
custom-sync,button,Sync now,Sync now,,pass,duplicate
locked-save,button,Save,Requires edit access,,inspect,inspect
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Icon button | Keyboard focus and pointer hover | Same concise command is understandable |
| Shortcut | Tooltip includes key combination | Shortcut is visible without polluting the name |
| Disabled control | Unavailable action with explanation | Reason is discoverable without focus trap |
| Dynamic control | Inserted after route or AJAX update | Tooltip and accessible name initialize once |
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Give every control a stable semantic role and concise accessible name.
- Remove duplicate title, aria-label, or description sources after checking the accessibility tree.
- Adopt the supported WordPress tooltip mechanism where it fits the plugin architecture.
- Repair overlay positioning, focus handling, translated text, and dynamic initialization.
- Run the matrix again across supported WordPress versions before release.
Decision rule
Approve a control when its purpose is understandable without hover, the tooltip adds useful context without duplicate speech, and keyboard, screen reader, zoom, and dynamic states remain predictable.
Production verification checklist
- Icon-only controls have one correct accessible name.
- Tooltips appear and close predictably for supported input modes.
- Shortcut text is visible and understandable without changing the command name.
- No plugin control loses focus, clips essential text, or initializes duplicate overlays.
Field notes
- Use browser accessibility inspection alongside the spoken screen reader output.
- Test translated strings and long commands because overlay size can change materially.
- Do not put critical instructions only in a tooltip.
Questions teams ask during testing
Can this be tested on staging?
Start on staging with production-like versions, roles, data volume, browser behavior, cache, and integrations. Finish with one controlled production fixture when the result depends on the real CDN, email route, worker clock, crawler response, or browser storage.
What evidence should be retained?
Keep the smallest useful evidence set: exact versions, stable IDs, UTC timestamps, sanitized request or log excerpts, expected result, actual result, decision, and final verification. Redact customer data, cookies, secrets, order keys, and full advertising identifiers.
When should the change be rolled back?
Roll back when a revenue, privacy, accessibility, security, publishing, or lead path fails and the cause cannot be isolated inside the approved maintenance window. Preserve the failed fixture before rollback so the next attempt starts with facts.
Mistakes to avoid
- Do not change several production layers at once. Preserve the failing evidence and isolate one variable per test.
- Do not treat a successful request, quiet log, or correct screenshot as proof that the complete user outcome is correct.
- Do not leave debug logs, test records, broad credentials, temporary roles, or browser overrides active after verification.
- Do not close the work without recording versions, fixture IDs, UTC timestamps, owner, result, and rollback point.
What to tell the client or owner
Give the owner the affected versions, exact fixture, stable IDs, UTC timeline, before and after evidence, decision, rollback point, unresolved risks, and next review date.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, fix a WordPress admin accessibility regression.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Add translated and Elementor tooltip fixtures
Extend the control inventory with the WordPress 7.1 translated tooltip overflow test, then run the builder-specific Elementor 4.2.2 tooltip compatibility matrix across panels, dialogs, responsive mode, and dynamic controls.
Helpful references