The WordPress 7.1 roadmap plans to enforce the iframed editor for block themes. Blocks using Block API version 2 or lower and scripts that query the top-level admin document can load styles or controls in the wrong document, lose event handling, or render differently from the front end.
Use this for custom blocks, block themes, editor extensions, metabox bridges, portals, overlays, media pickers, style injection, and code that reads window, document, or viewport dimensions.
Quick answer
WordPress 7.1 Iframed Editor Block API v2 Compatibility Audit should be handled with a narrow evidence-first workflow: inventory block versions, find parent dom assumptions, run editor workflow, then verify the result before making broader changes.
What to check first
- Inventory registered blocks and record apiVersion from block.json or server registration.
- Search editor JavaScript for document.querySelector, window dimensions, global style injection, portals, and parent-frame access.
- Test each block in a block theme with WordPress 7.1 beta, including selection, inserter, transforms, drag, preview, save, and reload.
- Move editor canvas styles into the supported editor stylesheet path and migrate blocks to Block API version 3.
- Compare editor and front-end layout at responsive widths and inspect both frame and parent console errors.
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 |
|---|
| Inventory block versions | Inventory registered blocks and record apiVersion from block.json or server registration. | Every custom block uses a supported API version or has a documented migration owner. |
| Find parent DOM assumptions | Search editor JavaScript for document.querySelector, window dimensions, global style injection, portals, and parent-frame access. | Editor styles load inside the canvas and admin controls stay in the parent where intended. |
| Run editor workflow | Test each block in a block theme with WordPress 7.1 beta, including selection, inserter, transforms, drag, preview, save, and reload. | Selection, transforms, overlays, media controls, save, and reload work without console errors. |
| Migrate styles and API | Move editor canvas styles into the supported editor stylesheet path and migrate blocks to Block API version 3. | Responsive units and media queries match the canvas and front-end expectations. |
Why this usually happens
- The editor canvas and admin controls live in different documents when the editor is iframed.
- CSS loaded only into wp-admin may never reach the canvas.
- Viewport units inside an iframe use the canvas size rather than the full browser window.
- DOM queries and event listeners attached to the parent document cannot see canvas nodes.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
rg -n '"apiVersion"\s*:\s*[12]|document\.querySelector|window\.(innerWidth|parent)|createPortal' wp-content/plugins wp-content/themes
# Review matches manually. Do not bulk-replace DOM targets.
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.
- Inventory block versions
- Find parent DOM assumptions
- Run editor workflow
- Migrate styles and API
- Compare frame and front end
What to tell the client or owner
Provide block name, apiVersion, theme type, failing action, frame or parent context, console stack, stylesheet handle, DOM assumption, and migration result.
Production verification checklist
- Every custom block uses a supported API version or has a documented migration owner.
- Editor styles load inside the canvas and admin controls stay in the parent where intended.
- Selection, transforms, overlays, media controls, save, and reload work without console errors.
- Responsive units and media queries match the canvas and front-end expectations.
Mistakes to avoid
- Do not judge the fix by one browser or the homepage only.
- Do not delete evidence before recording usernames, file paths, timestamps, and response headers.
- Do not add a cache, security, or tracking plugin while the original problem is still unclear.
- Do not leave test users, temporary debug logs, or broad API keys active after verification.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, malware risk, 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, audit a custom block for WordPress 7.1.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Run the inserted-block compatibility fixture
Turn the inventory into the WordPress 7.1 iframed editor Block API v2 test, covering inserted blocks, editor assets, document access, events, roles, saves, and front-end output.
Helpful references