A client called me last week, pretty rattled. Their custom Gutenberg blocks had been solid for years, and now they looked completely off in the post editor. Weird padding, font sizes all over the place. On top of that, they were getting browser warnings about “legacy blocks.” Another WordPress update, another head-scratcher. This is the kind of mess that shows up when nobody is watching Gutenberg block iframe compatibility.
WordPress is moving the post editor to run inside an iframe, and this is no longer a maybe. WordPress 6.9 added a set of compatibility measures ahead of the full transition in WordPress 7.0. The official dev note has the specifics, but the short version is that your old blocks are on borrowed time.
Why the Gutenberg block iframe matters for your blocks
The point of the iframe shift is isolation, and that is a good thing. For years, admin styles have leaked into the editor canvas and caused real headaches for block and theme developers. You could lose hours chasing some rogue CSS that only showed up in the editor, which made the “what you see is what you get” promise feel more like a suggestion. Put the editor in an iframe and those admin styles stay contained. Viewport units and media queries behave the way they should. It makes styling far simpler, but only if your blocks are ready for it.
Legacy blocks are where it goes wrong. If your block is registered with apiVersion 2 or lower, WordPress 6.9 already throws browser warnings, and that is worth treating as more than a gentle nudge. These older blocks still run outside the iframe for now, but that will not last. Once WordPress 7.0 makes the editor fully iframed, those blocks are likely to break or render with unpredictable styling. The block.json schema now only accepts apiVersion: 3 for new or updated blocks. Version 1 or 2 will not pass validation.
The first instinct, and I have watched people make this mistake more times than I can count, is to patch it with custom CSS. Add an !important here, a more specific selector there. Trust me, that way lies a nightmare. You end up fighting the architecture WordPress is moving toward, and you spend more time babysitting fragile CSS overrides than a proper fix would have taken.
The fix: update your apiVersion
The dependable fix for Gutenberg block iframe compatibility is to update your blocks to apiVersion: 3. That tells WordPress the block is built for the iframe environment, so it renders correctly and respects the editor’s isolated styles instead of fighting them.
{
"apiVersion": 3,
"name": "bbioon/custom-block",
"title": "bbioon Custom Block",
"category": "widgets",
"icon": "smiley",
"description": "A custom block by bbioonThemes.",
"textdomain": "bbioon-blocks",
"editorScript": "file:./index.js",
"editorStyle": "file:./index.css",
"style": "file:./style-index.css"
}Above is a minimal block.json example with "apiVersion": 3. Set this on every custom block you have. Once updated, test them properly inside an iframe-based editor (you can turn that on for testing if it is not fully live on your setup yet). It is a bit of work, but it is what keeps the blocks working through the transition. Check that your styling and JavaScript still behave the way you expect inside that isolated context.
So what’s your move?
The core team is pushing these changes to make the editor more stable and predictable. Ignoring the apiVersion warning is a bit like ignoring a check engine light. The car runs for a while, and then one day it leaves you stranded. Updating your blocks now saves you a pile of refactoring and bug fixing when WordPress 7.0 lands, and you end up with a cleaner setup for future work.
This stuff gets complicated fast. If you are tired of debugging someone else’s mess and just want your site to work, drop my team a line. We have probably run into it before.
