WordPress 7.1 Forces the Post Editor Into an iframe: What Breaks on August 19

WordPress 7.1 ships on August 19, timed with WordCamp US in Phoenix. Most of what's in it is additive — new blocks, responsive styling controls, media handling improvements. One change is not additive, and it is the one worth your attention: the post editor canvas becomes an iframe on every theme, on every site, with no way to opt out.

If you maintain custom blocks for clients, or ship a plugin that adds anything to the editor screen, this is the release where code that has quietly depended on the editor sharing a document with the admin page stops working. You have about two and a half weeks.

What actually changes

Until now, WordPress ran two different editor environments:

The Site Editor has been iframed for a long time, which is why some teams have already hit and fixed these bugs. The post editor was the holdout — it rendered blocks directly into the admin page, sharing one document with the WordPress admin around it.

From 7.1, the canvas is wrapped in <iframe name="editor-canvas"> unconditionally. That isolation is the point: it means viewport units and media queries inside your block measure the canvas, not the browser window, so what you see in the editor finally matches the front end. It is a genuinely good change. It also means every assumption your JavaScript made about "the editor is on this page" is now wrong.

The escape hatch that closes

This is the part that catches people, because it explains why your blocks might look fine today and break on August 19.

In WordPress 7.0, released this April, the decision to iframe was made per post, based on what was actually inserted into it. If a post contained a block still declaring Block API version 1 or 2, WordPress backed off and disabled the iframe for that editing session — for every block on the page, not just the legacy one.

So a single un-migrated block has been acting as a site-wide off switch. If your client sites have one old block sitting in a reusable pattern somewhere, you have never seen iframed mode, and you have no idea whether the rest of your blocks survive it.

In 7.1 the conditional logic is gone. There is no block you can insert, no filter, no constant that turns it back off.

What breaks

The failures cluster into five patterns. All of them come down to the same root cause: your code reaches for the global window or document, and the block no longer lives in that document.

1. Viewport measurements report the wrong width

// Reports the admin page width, not the canvas width
const isMobile = window.innerWidth < 782;

Any block that switches layout based on measured width will now measure the browser window while rendering inside a canvas that might be half that wide. Responsive previews are the obvious casualty — the block renders its desktop layout inside a phone-width canvas.

2. Click-outside listeners stop firing

// Listening on the wrong document
document.addEventListener( 'click', closePopover );

Clicks inside the canvas dispatch against the iframe's document. A listener bound to the parent document never hears them. The symptom is a dropdown, colour picker, or settings popover that opens and then refuses to close — which users report as "the editor is frozen".

3. Editor styles don't load

This one produces the most support tickets. Styles enqueued through enqueue_block_editor_assets load into the admin page, outside the iframe. The canvas never receives them, so your block renders unstyled in the editor while looking perfectly correct on the front end.

The fix is to stop enqueueing editor styles that way and declare them in block.json instead:

{
  "apiVersion": 3,
  "name": "acme/feature-grid",
  "editorStyle": "file:./index.css",
  "style": "file:./style.css"
}

WordPress injects anything registered via editorStyle into the iframe document for you. Use enqueue_block_editor_assets only for things that genuinely belong to the admin chrome — sidebar panels, toolbar buttons, plugin UI outside the canvas.

4. Admin-scoped CSS selectors stop matching

/* Neither ancestor exists inside the iframe */
.wp-admin .acme-block { border: 1px solid red; }
.block-editor-page .acme-block__title { font-weight: 700; }

Selectors anchored to .wp-admin, .block-editor-page, or any other admin-level wrapper match nothing inside the canvas, because those classes live on the parent document's body. Scope your editor CSS to the block's own class instead.

5. Third-party libraries find nothing

Anything you initialise with a global query — a lightbox, a slider, a charting library, a masonry layout — runs document.querySelectorAll() against the parent document, finds zero matching elements, and silently does nothing. No error, no styling, no clue. Libraries that accept a root or context argument need to be handed the canvas document explicitly.

The fix pattern

Rather than hunting for a global replacement, get a reference to the element you're actually rendering into and derive the document and window from it. useRefEffect from @wordpress/compose is the idiomatic way:

import { useRefEffect } from '@wordpress/compose';

const ref = useRefEffect( ( element ) => {
	const { ownerDocument } = element;
	const { defaultView } = ownerDocument;

	const onResize = () => {
		// defaultView is the iframe's window — or the real one, if not iframed
		setIsNarrow( defaultView.innerWidth < 782 );
	};

	defaultView.addEventListener( 'resize', onResize );
	ownerDocument.addEventListener( 'click', onDocumentClick );
	onResize();

	return () => {
		defaultView.removeEventListener( 'resize', onResize );
		ownerDocument.removeEventListener( 'click', onDocumentClick );
	};
}, [] );

return <div { ...useBlockProps( { ref } ) }>{ /* ... */ }</div>;

The reason this pattern is worth adopting wholesale is that it is correct in both environments. element.ownerDocument resolves to the iframe document when iframed and the normal document when not, so you don't need branching logic and you don't need to know which mode you're in.

apiVersion 3 is a signal, not a fix

You will see advice that amounts to "set apiVersion to 3 and you're done". That is wrong in a way that will cost you.

Declaring version 3 in block.json tells WordPress your block is ready to render inside an iframe. It is a one-line change and it changes nothing about how your block behaves. In 7.0, that declaration was load-bearing — it was the signal that let WordPress decide whether to iframe at all. In 7.1, with the iframe mandatory, the declaration no longer buys you protection; it just describes your intent.

Do the audit, fix the globals, then bump the version. Bumping first only removes the warning label from an unfixed problem.

How to test both states

You need to check your blocks in both environments, because your clients will be spread across versions for months after August 19.

Iframed: install the Gutenberg plugin at 22.6 or later on a WordPress 7.0 site, or run WordPress 7.1 Beta 1 directly. Both enforce the iframe.

Non-iframed: WordPress 7.0 with no Gutenberg plugin, then insert any block still declaring API version 1 or 2 into the post. That flips the escape hatch and disables the iframe for that session.

To confirm which state you're actually in, run this in the browser console with the editor open:

// true when the canvas is iframed
!! document.querySelector( 'iframe[name="editor-canvas"]' )

Or, from inside a block's own code, compare documents:

element.ownerDocument !== document // true when iframed

A checklist for the next two weeks

1. Inventory your custom blocks. Every client site with bespoke blocks, every commercial plugin that ships blocks, every theme with editor JavaScript.
2. Grep for globals. Search your block source for window., document., document.querySelector, and addEventListener bound to document. This finds the majority of the damage in one pass.
3. Move editor styles into block.json. Anything currently going through enqueue_block_editor_assets that styles block content belongs in editorStyle.
4. Grep your CSS for .wp-admin and .block-editor-page as ancestor selectors in editor stylesheets.
5. Check what your page builder does. If clients are on Breakdance, Bricks, or Elementor, their builders run outside the block editor — but any blocks those sites still use in the post editor are in scope. See our Breakdance vs Bricks comparison for where each one sits relative to core.
6. Test on a staging clone, not production. Our staging site guide covers spinning these up per client if you don't already have a routine.
7. Bump apiVersion to 3 once the block genuinely passes in iframed mode.

What is not changing

Worth saying clearly, because a lot of coverage in June and July said otherwise: React 19 is not in WordPress 7.1.

The upgrade was pulled on July 24, after core found incompatibilities in how React 18 and 19 interact and in the ways plugins consume React. WordPress 7.1 ships on React 18.3. React 19 lives on as an opt-in experiment behind the gutenberg-react-19 flag in Gutenberg 23.4 and later, under Settings → Gutenberg.

That removes a deadline but not the work. The APIs React 19 drops have been deprecated for roughly six years, and they will come back around: string refs, defaultProps on function components, and legacy context. If you already scheduled a React audit for August, keep it — you just have more room to do it properly. We covered the original expectation in our WordPress 7.1 Beta 1 guide; treat this as the correction to it.

Deprecations to catch in the same pass

Since you'll have the editor code open anyway, four smaller changes land in the same cycle:

• __next40pxDefaultSize is hard-deprecated across roughly twenty components including TextControl, BoxControl, BorderControl, FontSizePicker, and RangeControl. The 40px size is now simply the default; the opt-in prop is going away.
• @wordpress/reusable-blocks is deprecated as of Gutenberg 23.6. Its store actions, selectors, and components log warnings.
• useResizeCanvas() is deprecated and non-operational, superseded by the new responsive styling work in Gutenberg 23.5.
• @wordpress/icons v15 sets fill="currentColor" on all 330 icons. If you tint icons with the CSS fill property, switch to color.

The short version

The iframe is a good change that fixes a real class of editor/front-end mismatch, and it will break custom code that assumed the editor shared a document with the admin. The fix is mechanical and the pattern is the same everywhere: derive document and window from the element you're rendering into, never from the globals.

The reason to do it this week rather than on August 20 is that the failures are quiet. Nothing crashes. Styles just go missing and popovers just stop closing, on client sites, discovered by clients. That is a worse Monday than an afternoon of grepping.

If you manage enough sites that tracking which ones have custom blocks is itself the hard part, an inventory tool earns its keep here — see our roundup of WordPress maintenance tools for agencies.