WordPress 7.1 adds a theme.json-only custom state for the current Navigation Link. It can centralize current-page styling, but existing selectors for current-menu-item classes, ancestor links, archives, and mobile overlays may compete with the new state.
Use this for block themes and theme plugins that style active menu links, current ancestors, service navigation, category archives, or account areas.
Quick answer
Build a menu fixture with normal pages, parent and child pages, category archives, custom links, a home link, and mobile overlay navigation. Compare existing current-menu selectors with the new custom state, then test hover and focus-visible on the current link. Keep a non-color cue and verify that exactly the intended link is announced and styled.
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 |
|---|
| Exact page | Open a page linked directly in the primary menu | One intended link has current styling and aria-current |
| Child page | Open a grandchild below a parent menu item | Ancestor and exact-item behavior match the approved design |
| Archive | Open a category or product archive | Current state follows the intended archive owner |
| Mobile overlay | Open the same routes in expanded responsive navigation | Current, hover, and focus remain distinct and readable |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Map current-state owners | Inventory current-menu-item, current-menu-ancestor, aria-current, Navigation Link, and custom variation selectors. | Exactly the intended link or approved ancestor receives current styling. |
| Build route fixtures | Create routes for exact current pages, descendants, archives, home, query strings, and external links. | The rendered link exposes the expected aria-current value. |
| Add the theme.json state narrowly | Compare the custom current state with legacy class-based rules and selector specificity. | Current, hover, and focus-visible states remain distinguishable. |
| Resolve selector conflicts | Test current plus hover, current plus focus-visible, and current inside mobile or tablet styling. | Desktop and responsive navigation use the same approved ownership logic. |
What to check first
- Inventory current-menu-item, current-menu-ancestor, aria-current, Navigation Link, and custom variation selectors.
- Create routes for exact current pages, descendants, archives, home, query strings, and external links.
- Compare the custom current state with legacy class-based rules and selector specificity.
- Test current plus hover, current plus focus-visible, and current inside mobile or tablet styling.
- Check visible state, aria-current value, keyboard focus, and screen reader context.
Field notes
- Record the rendered class list and aria-current value for each fixture route.
- Include a menu item with a long label and one with an icon.
- Test logged-in account navigation separately when routes are dynamic.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
// Browser console on each fixture route
[...document.querySelectorAll('.wp-block-navigation a')].map(a => ({
text: a.textContent.trim(),
current: a.getAttribute('aria-current'),
classes: a.parentElement?.className,
color: getComputedStyle(a).color
}));
Why this usually happens
- Legacy menu classes and the new state can target the same link with different specificity.
- Ancestor and exact-current logic are different even when designs treat them similarly.
- A current-state background can hide focus or hover changes in a responsive overlay.
Decision rule
Do not ship when multiple unrelated links appear current, the current item lacks a non-color cue where one is required, focus disappears on the current link, or archive and ancestor behavior changes without approval.
Production verification checklist
- Exactly the intended link or approved ancestor receives current styling.
- The rendered link exposes the expected aria-current value.
- Current, hover, and focus-visible states remain distinguishable.
- Desktop and responsive navigation use the same approved ownership logic.
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.
- Map current-state owners
- Build route fixtures
- Add the theme.json state narrowly
- Resolve selector conflicts
- Retest focus and mobile navigation
Mistakes to avoid
- Do not test the homepage route only.
- Do not delete legacy selectors before checking plugins that still render classic menus.
- Do not communicate current state by a subtle color change alone.
- Do not forget ancestor and archive routes.
Questions teams ask during testing
Can plugins register this custom state through the editor UI?
The dev note describes the current custom state as theme.json-only for Navigation Link.
Does it replace aria-current?
No. Visual styling and semantic current-page information should agree.
Should parent links appear current on child pages?
That is a design and information-architecture decision. Define the expected ancestor behavior before testing.
What to tell the client or owner
Share the route, menu item, expected owner, class list, aria-current value, theme.json path, matched selector, viewport, state combination, and screenshot.
When HandL WP should help
HandL WP can map legacy menu selectors, build exact and ancestor route fixtures, implement the new state narrowly, and verify semantic, visual, keyboard, and mobile behavior.
If this is active on a production site, test a WordPress navigation change.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references