Block Editor Focus Restoration After Closing Nested Block Inserters in WordPress 6.2+

Answer

Should WordPress adopt an explicit focus‑return API? Yes, but only as a fallback for complex nested inserters. Core currently relies on the browser’s native focus management, which works for simple cases but fails when the inserter’s portal or the block toolbar is removed from the DOM during the close animation. An explicit API would let the core, themes, and plugins coordinate a deterministic return target without depending on the element’s presence.

Why the current behaviour is inconsistent

• WordPress 6.2 introduced FocusLock around the inserter panel and ARIA labels on the trigger button.
• When the inserter is dismissed, core calls focus() on the trigger button if it still exists. If the button is unmounted or moved, the browser falls back to document.body or the nearest focusable ancestor.
• Many themes and plugins replace or reorder the block toolbar, or wrap the editor in custom portals, causing the trigger button reference to be lost.

How to avoid interfering with focus restoration

1. Keep the block toolbar and inserter trigger buttons mounted. If you need to hide them, use CSS visibility:hidden or opacity:0 instead of unmounting.
2. Do not add global focus listeners that call preventDefault() or move focus during the inserter’s open state.
3. When manipulating the editor DOM, defer changes until the inserter store’s __unstableIsInserterOpened selector returns false.
   • Example: useEffect(() => { if (!isInserterOpened) { /* safe DOM changes */ } }, [isInserterOpened]);
4. Use the official wp.data selectors (getInserterItems, isInserterOpened) instead of querying the DOM directly.

Testing strategy for consistent focus behaviour

Combine automated and manual tests to cover screen‑reader and keyboard‑only users.

1. Automated unit tests – use @testing-library/react and userEvent.tab() to simulate opening and closing the inserter.
   • Assert that document.activeElement after dismiss matches the element that had focus before the inserter opened.
2. End‑to‑end tests – run the core test:e2e suite against multiple themes (Twenty Twenty‑Four, a block‑heavy theme) and plugins that add custom block variations.
3. Assistive‑technology checks – manually test with NVDA + Firefox, JAWS + Chrome, and VoiceOver + Safari. Verify that the announced focus matches the visual focus after the inserter is closed.
4. Regression guard – add a snapshot of document.activeElement to the CI pipeline and fail if it changes unexpectedly.

One diagnostic detail needed

Does your project currently unmount the block toolbar or the inserter trigger button when the inserter is opened, or use preventDefault() in a global focus handler?