If you run a WordPress site, then you know that spam is a real annoying problem whether it comes to contact forms, WordPress comments, or user registrations.

The good news is that stopping spam in WordPress is a lot easier than you probably think, and you don’t need expensive tools either.

We have spent over 16 years testing anti-spam plugins, tools, and refining strategies to keep WPBeginner and our other business websites safe from daily spam attacks.

In this ultimate guide, we’ll walk you through how to block each type of WordPress spam, step by step from the basics to advanced modern automated spam protection. These are the exact methods we’re using to protect our own websites.

We’re covering a lot of ground in this ultimate guide, so use the quick links below to jump straight to the section you want to learn about first:

1. Free Built-In Settings to Turn On First

WordPress comes with several anti-spam options that can protect your site against spam. These built-in options won’t stop every bot, but they will remove the easiest targets right away.

We always recommend turning these settings on first, because they cost nothing and take only a few minutes to set up.

Tighten Your WordPress Discussion Settings

To prevent comment spam, the built-in discussion settings in WordPress act as your first line of defense. They allow you to control who can post, what kind of links are permitted, and how much control you have over the conversation.

To configure these anti-spam controls, go to Settings » Discussion in your WordPress dashboard.

The most useful tool on this screen is the comment moderation queue. This tool acts as a holding area that keeps submissions hidden from the public until you have a chance to look them over.

Because nothing goes live automatically, spam never reaches your visitors, even if it manages to get past your other filters.

To turn this on, scroll down to the ‘Before a comment appears’ section and check the box next to ‘Comment must be manually approved.’

If you want, you can also enable ‘Comment author must have a previously approved comment.’ This lets returning commenters post without waiting for approval. However, be sure to review your published comments regularly since they won’t appear in your moderation queue.

After that, scroll to the ‘Comment Moderation’ box, where you’ll find a setting that limits links. Because spam comments almost always contain web addresses, WordPress can automatically hold any submission that includes too many links.

The field labeled ‘Hold a comment in the queue if it contains [X] or more links’ is set to 2 by default. Lowering that number to 1 will help you catch even more junk.

On the same screen, you can use the comment blocklist to automatically filter out unwanted content. This tool looks for specific words, names, email addresses, or web addresses and sends any matching comment straight to the trash.

In the ‘Disallowed Comment Keys’ box, you can paste your own trigger words, putting one on each line, and then save your changes.

Require a Name and Email, and Hold First-Time Commenters

Healthy discussions start with real people. Requiring commenters to enter a name and email encourages more thoughtful conversations and discourages anonymous drive-by comments.

Most genuine visitors won’t mind providing these details, and it helps create a more welcoming and trustworthy community around your website.

To enable this, scroll to the ‘Other comment settings’ section and check the box next to ‘Comment author must fill out name and email.’

If you want to master the review process and manage your queue efficiently, our beginner’s guide to moderating comments in WordPress covers the full workflow.

Disable Comments Where You Do Not Need Them

Depending on the type of website you have, you may not need a comment section at all. If that’s the case, then you can simply disable comments entirely and that’ll get rid of the WordPress comment spam problem once and for all.

The most thorough option is the code method, which disables comment support across your entire site at once. It’s safest to add the snippet with a free code snippets plugin like WPCode rather than editing your theme’s files directly, so a theme update can’t undo it.

add_action('admin_init', function () {
    // Redirect any user trying to access comments page
    global $pagenow;
    
    if ($pagenow === 'edit-comments.php') {
        wp_safe_redirect(admin_url());
        exit;
    }

    // Remove comments metabox from dashboard
    remove_meta_box('dashboard_recent_comments', 'dashboard', 'normal');

    // Disable support for comments and trackbacks in post types
    foreach (get_post_types() as $post_type) {
        if (post_type_supports($post_type, 'comments')) {
            remove_post_type_support($post_type, 'comments');
            remove_post_type_support($post_type, 'trackbacks');
        }
    }
});

// Close comments on the front-end
add_filter('comments_open', '__return_false', 20, 2);
add_filter('pings_open', '__return_false', 20, 2);

// Hide existing comments
add_filter('comments_array', '__return_empty_array', 10, 2);

// Remove comments page in menu
add_action('admin_menu', function () {
    remove_menu_page('edit-comments.php');
});

// Remove comments links from admin bar
add_action('init', function () {
    if (is_admin_bar_showing()) {
        remove_action('admin_bar_menu', 'wp_admin_bar_comments_menu', 60);
    }
});

Our guide on how to completely disable comments in WordPress walks through that snippet along with the other options.

If you’d rather not go site-wide, you can also turn comments off on individual pages. This is handy when you only want them gone on specific pages, like your Contact or About pages, which rarely need a comment section.

To do this, open the page in the WordPress content editor. Then click the ‘Discussion’ option in the right-hand sidebar and select ‘Closed.’

You can also stop spam from piling up on older content without touching your newer posts. If you don’t expect comments on old posts, then WordPress can close them automatically after a set number of days.

This gives spam bots fewer chances to target your archived content.

To set this up, head to Settings » Discussion and find the ‘Other comment settings’ section. Check the box next to ‘Automatically close comments on posts older than [X] days’, then set a sensible limit such as 30 or 90 days.

Disable Trackbacks and Pingbacks

Trackbacks and pingbacks notify you when another website claims to have linked to one of your blog posts.

While they were originally designed to help bloggers connect conversations across different websites, they’re now commonly abused by spammers to send fake link notifications.

Turning this feature off completely removes a whole category of junk notifications from your dashboard.

To disable these notifications, go to the Settings » Discussion screen in your WordPress dashboard. Here, uncheck the box next to ‘Allow link notifications from other blogs (pingbacks and trackbacks) on new posts.’

2. Set Up Modern AI-Powered Spam Bot Protection for WordPress

In the era of AI where automated spam is increasing, the best defense against it is a modern AI-powered spam protection for WordPress.

These spam filtering solutions automatically detect and block spam on your WordPress comments, contact forms, and user registrations without the use of CAPTCHA which can hurt conversions.

On WPBeginner, we use ActiveLayer for this. It is AI-powered and runs server-side, so it stops spam invisibly, without a CAPTCHA and it’s GDPR compliant.

In the last 30 days, it has blocked over 25,739 spam comments and contact form submissions on our website. It even shows you a confidence score, and the reason behind every submission it flags, not just a pass-or-fail verdict when you look at their logs.

The free plan includes 1,000 spam checks with no credit card, and paid plans start at around $4 per month billed yearly.

The two other popular spam filtering plugins for WordPress you could try are Akismet or CleanTalk.

Akismet is very popular and still is a good fit for personal blogs, where its “name your price” plan can be free for non-commercial sites. But they have raised their prices significantly for commercial sites which is quite expensive for smaller businesses. For a business site, we would point you to either ActiveLayer or CleanTalk.

Whichever tool you choose, stick to just one, because running two spam filters at once can conflict and block real visitors. The benefit of these spam protection plugins are that they integrate with all other popular contact form plugins by default.

3. Power-User Tips for Stopping WordPress Comment Spam

So far we’ve configured the built-in spam prevention settings in WordPress, and an automated spam filtering plugin for WordPress. The combination of these two should block most spam.

However if you are not able to set up modern AI spam protection due to costs or another reason, then you can use one of these tips below to combat comment spam in WordPress.

Add a Free CAPTCHA to Your Comment Form

CAPTCHA is a simple test that most human visitors pass without any effort, while automated scripts fail it. We recommend adding Cloudflare Turnstile CAPTCHA to your WordPress comments because it’s free and fairly straight forward to set up.

To set it up, install and activate the free Simple Cloudflare Turnstile plugin. You will be asked to create a free account on Cloudflare’s website and connect it with the plugin.

Once that’s done, you can scroll to the ‘Enable Turnstile on your forms’ section. Simply check the boxes to protect all your WordPress forms and click ‘Save Changes’.

Here’s our detailed guide on how to add Cloudflare Turnstile CAPTCHA in WordPress.

Google reCAPTCHA is another option, which you can add with the Advanced Google reCAPTCHA plugin. We no longer recommend it because Google has capped their free tier at 10,000 assessments per month for your entire organization whereas Cloudflare Turnstile stay free without limits.

Limit or Require Login to Comment

Another really effective way to stop comment spam in WordPress is to control who’s allowed to participate in comments.

If your comment section is open to everyone, then spammers can continuously flood your forms with automated links. Restricting comments to registered account holders ensures that only verified users can post. This forces a level of accountability that most bots will not bother trying to bypass.

Because it requires readers to go through the extra step of creating and logging into an account, this approach is best suited for membership sites, online forums, and private communities.

If you run an open, public blog, then we’d recommend using an automated filtering service or a reader challenge instead as those add less friction.

If you do decide to turn this restriction on, go to Settings » Discussion in your WordPress dashboard. Under the ‘Other comment settings’ section, check the box next to ‘Users must be registered and logged in to comment.’

As always, don’t forget to save your changes.

Use Antispam Bee for Free Keyword and Pattern Filtering

Some spam slips through basic checks by mimicking human writing. This is where a dedicated filtering plugin can help protect your site.

Antispam Bee is an excellent free, privacy-friendly anti-spam plugin that doesn’t require an API key or account registration. Installing Antispam Bee gives you a powerful set of local rules to analyze comment data before it even hits your database.

Once it’s activated, you can configure your rules by going to Settings » Antispam Bee.

We recommend enabling the options to:

• Trust approved commenters.
• Mark as spam.
• Do not delete.
• Use regular expressions (which allows the plugin to scan for known text and link patterns).

You should also check the box to ‘Look in the local spam database.’ This allows Antispam Bee to cross-reference new submissions against previous spam history on your site.

Under ‘Advanced,’ you can set Antispam Bee to delete existing spam after a set number of days, which keeps your database tidy without any manual effort.

We highly recommend leaving the email notifications for spam turned off in this section. A busy website can attract hundreds of automated submissions a day, and these alerts will quickly flood your inbox.

If you want to try one more free tweak, then you can remove the website address field from the comment form.

Our step-by-step guide on how to remove the website URL field from the comment form shows you how to do this in just a few quick steps.

4. Stopping WordPress Contact Form Spam (Best Practices)

Contact and lead forms are among the most attacked parts of any WordPress site. We know this firsthand because we once had to combat more than 18,000 spam entries flooding a single form.

We use WPForms to build forms on WPBeginner, and it’s a popular form builder plugin used by over 5 million websites. Their free version includes smart anti-spam protection, CAPTCHA integrations with Google / Cloudflare Turnstile, and the paid plans add the filtering options we cover below.

Other popular form builders like Gravity Forms and Fluent Forms have similar anti-spam settings, so check the options in whichever form builder plugin you use. We will show WPForms here because it’s what we use and consider the best fit for beginners.

Enable Default Anti-Spam Token (or Similar HoneyPot)

To combat lead form spam, WPForms silently attaches a unique, time-sensitive token to your form on every page load. The anti-spam token blocks automated scripts, which means spam entries are blocked before they reach your inbox.

It’s turned on by default for new forms, but it’s worth confirming.

Open your form, go to Settings » Spam Protection and Security, and make sure ‘Enable modern anti-spam protection’ is switched on.

This is a modern version of the Honeypot technology which most WordPress form plugins come with, so it may be labeled as Honeypot in another form tool that you might be using.

Enable a CAPTCHA on Your Contact Form

More aggressive bots mimic human browsing and slip past the invisible token. Adding a visible CAPTCHA field stops them by forcing a challenge they can’t read or solve.

WPForms has both Cloudflare Turnstile and Google reCAPTCHA built in, and we default to Turnstile here. It’s free for everyone and runs its checks in the background, so most real visitors pass without solving a puzzle.

To set it up, go to WPForms » Settings » CAPTCHA and choose ‘Cloudflare Turnstile’.

Then add the Site Key and Secret Key from your Cloudflare account, and save your settings.

Finally, add the CAPTCHA field to each form you want to protect.

For a full walkthrough, see our guide on how to add Cloudflare Turnstile CAPTCHA in WordPress.

Google reCAPTCHA is also selectable on that same WPForms » Settings » CAPTCHA screen. We default to Turnstile because it’s free without limits, but reCAPTCHA still works if you prefer it.

If you’d rather not send visitor data to Google or Cloudflare, then WPForms’ Custom Captcha field (available on any paid plan) builds the challenge on your own server instead.

Add the field, then set it to a random math problem or your own question and answer.

Use Time-Based Behavioral Checks to Stop Contact Form Spam

A real person needs several seconds to read a question and fill out a form, while a bot submits in a fraction of a second. Time-based checks flag those impossibly fast submissions without changing anything the visitor sees.

With WPForms, the ‘Enable minimum time to submit’ option is enabled by default with a minimum time to submit of 2 seconds. However, you can update the minimum time to any value you like.

Block Form Submission by Country, IP, Email Address, and More

Some spam form submissions still gets through unless you screen the content itself. In the Pro version, WPForms lets you block entries by specific email address, by keyword, and by country or IP address.

To block a sender, open your form, select the Email field, open the Advanced tab, choose Denylist, and enter the addresses or domains to ban. A wildcard like *@example.com blocks an entire domain.

To block spammy phrases, go to Settings » Spam Protection and Security.

Turn on ‘Enable keyword filter’, open ‘Edit keyword list’, and add each term on its own line.

And if you only serve certain regions, turn on ‘Enable country filter’ on the same screen to allow or deny locations.

Alternatively if your WordPress form solution doesn’t have this option, you can also block IP addresses in WordPress.

5. Stopping Spam User Registrations in WordPress (Best Practices)

On a membership site or WooCommerce store, spam registrations are more than a nuisance. Fake accounts clog your user database and skew your customer and email metrics.

Here’s what you can do to prevent spam user registrations in WordPress.

Turn Registration Off When You Do Not Need It

If you’re not running a membership site or an eCommerce store, then you likely don’t need to allow user registration. The easiest thing to prevent user registration spam there is to turn it off.

Simply go to Settings » General in your WordPress admin area, and uncheck the ‘Anyone can register’ box.

Require Email Confirmation Before an Account Activates

If you do need open registration, then the goal is to let only real people in while keeping spam bots out. The setting that stops the most fake signups is requiring a confirmed email address, or a manual review, before an account goes live.

Where that control lives depends on what plugin you’re using to manage user registration in WordPress. You will want to start with your platform’s default setting instead of bolting a general form plugin onto a system that already handles this.

If you run a WooCommerce store, then go to WooCommerce » Settings » Accounts & Privacy. This is where you decide whether shoppers can create an account at all, limit account creation to checkout, or keep guest checkout on so no account creation is needed.

WooCommerce core doesn’t add a separate email-confirmation step on its own. If you want one, then you’ll need a custom email verification extension or the custom signup form covered below.

Other membership and course platforms handle account verification in their own settings, so start there:

• MemberPress: WordPress creates the account on registration, so pair it with the free User Verification plugin to keep the account inactive until the person confirms their email. See MemberPress’ documentation for the full details.
• BuddyPress and BuddyBoss: email activation is built in, so new members stay inactive until they click the activation link. Enable registration under Settings » General (BuddyPress) or BuddyBoss » Settings » Login & Registration. See BuddyPress documentation and BuddyBoss documentation for more details.
• LearnDash: registration runs on WordPress’s own user system, so there’s no native email-confirmation step. An account goes live the moment someone signs up. To hold new accounts until the email is verified, add that check at the WordPress or form level, using a user verification plugin or the custom WPForms registration form covered below.

If you’re building a custom registration form rather than using one of the systems above, then you can use WPForms User Registration addon which lets you turn on email activation under the form’s User Registration settings, with either an email confirmation link or manual admin approval.

Similar options are available in Gravity Forms, WSForm, and other popular WordPress form plugins. For the full walkthrough, see our guide on how to moderate new user registrations.

Add CAPTCHA and Honeypot to WordPress Signup Form

The same tips that protect your WordPress contact forms also work on WordPress signup form. Since you already set up Cloudflare Turnstile earlier, you can switch it on for your registration form in a click.

For a dedicated walkthrough, see our guide on how to add a CAPTCHA to your login and registration forms.

If you’re using the default WordPress registration page, then you can add hidden honeypot fields to your registration form with the free WP Armour plugin. The plugin logs every bot it blocks under WP Armour » Statistics.

Use AI-Powered Tools for Blocking WordPress Registration Spam

Honeypots and CAPTCHAs stop obvious bots, but they can’t spot someone signing up with a throwaway email or from a known-bad IP address.

That’s where automated detection helps. It screens each new signup against live reputation data and blocks the ones that look fraudulent.

ActiveLayer and CleanTalk both offer this for WordPress registrations, and you can switch it on for your signup form the same way you did for your contact forms.

6. Add a Site-Wide WordPress Firewall

A Web Application Firewall (WAF) screens every visitor and blocks malicious requests before they reach your site. Since most form spam is automated, a good firewall can stop a lot of it at the perimeter.

We recommend a DNS-level firewall, which filters traffic on the provider’s network before it touches your server.

On WPBeginner, we use Cloudflare, which has a free plan with basic firewall protection (setup requires pointing your domain’s nameservers to Cloudflare).

Our guide on how to set up the free Cloudflare CDN and firewall walks through it.

Plus, our roundup of the best WordPress firewall plugins compares the other options if you want to weigh them up.

7. Cleanup WordPress Spam and Ongoing Monitoring

Stopping new spam is only half the job. If you’re like most websites, you already have a backlog of old junk that needs cleaning up.

A quick cleanup keeps your database tidy and helps your new tools run at their best.

Bulk-Delete Existing Spam Comments

WordPress spam filter flags junk comments but doesn’t delete them, so they can build up in your spam folder and take up database space until you clear them out.

In your dashboard, go to Comments, click the ‘Spam’ filter at the top, and hit ‘Empty Spam’ to permanently clear everything your filters caught.

If you have thousands of junk comments, the dashboard can freeze or time out. A free plugin like WP Bulk Delete is faster and more reliable for big backlogs.

For other methods, see our guide on how to bulk delete WordPress comments.

Clean Out Existing Fake User Accounts

Leaving bot profiles in your database is a security risk and skews your analytics. That’s why it’s important to clean out these fake accounts.

For a handful, go to Users » All Users, click the ‘Subscriber’ user role filter (the role almost all registration bots use), select the fake accounts, and choose Delete from the ‘Bulk actions’ menu.

⚠️ Be very careful to select only fake Subscriber accounts, and never an Administrator account.

For thousands of accounts, the free WP Bulk Delete plugin can remove users by role, inactivity, or registration date in one sweep.

For more information, see our guide on how to bulk delete WordPress users by role.

Handle False Positives

No filter is perfect, so never auto-delete your spam folder without a quick glance first.

In Comments » Spam, hover over a legitimate comment and click ‘Not Spam’. That also teaches your filter to recognize similar comments as safe in the future.

Set a Monthly Anti-Spam Review Routine

A few minutes each month keeps spam from piling back up. Add these three checks to your maintenance routine:

• Scan for false positives: skim your spam comment folder and form entries so no real messages were caught by accident.
• Empty your spam folders: once you’ve rescued anything real, clear them to keep your database lean.
• Check your user list: glance at new registrations for gibberish usernames or suspicious email domains that slipped through.

Key Takeaways

Here is a summary of the best practices we have covered to completely protect your WordPress website from spam:

• Start with free WordPress settings: turn on comment moderation, tighten your link limits, build a comment blocklist, and disable trackbacks. These cost nothing and clear out the easiest spam.
• Use automated, invisible filtering: a server-side tool like ActiveLayer, Akismet, or CleanTalk blocks bots in the background without making real visitors solve puzzles.
• Layer your contact form defenses: honeypots alone no longer stop modern bots, so combine them with timing checks, token validation, and an automated filter.
• Secure your registrations: require email confirmation for new accounts and screen every signup with an automated tool.
• Add a site-wide firewall: a DNS-level firewall like Cloudflare blocks a lot of automated spam at the perimeter, before it ever reaches your forms.
• Run regular cleanup: bulk-delete old spam comments and fake accounts, then spend a few minutes each month checking for false positives.

Frequently Asked Questions About WordPress Spam Protection

Is free Akismet-style filtering enough, or do I need
more?

For a small personal blog with only comment spam, a single free filter like Akismet is usually enough. Once you add contact forms, signup forms, or user registration, you’ll want a service that protects those too, like ActiveLayer or CleanTalk.

Will adding a CAPTCHA hurt my form conversions?

It can. The extra step causes some real visitors to give up on the form. This is why we prefer invisible, server-side detection that blocks bots without asking anyone to solve a puzzle.

Why am I still getting spam after installing an anti-spam
plugin?

Usually because the plugin only guards one entry point. If it protects your
comments but not your signup or contact forms, bots just move to those
instead, and older tricks like basic honeypots no longer stop modern bots. The
fix is a layered setup: your built-in WordPress settings, an automated
filter, and a firewall working together.

How do I stop fake user registrations without turning off signups
completely?

Turn on email confirmation so new accounts stay inactive until the person
clicks a link in their inbox, which bots can’t do. Pair it with a honeypot and
an automated filter, and real people can still sign up freely.

Can spam actually hurt my SEO or get my site
blacklisted?

It can, but it depends on where the spam is. Comment spam sitting in your moderation queue is never published, so search engines never see it and your SEO stays safe.

Published spam is the real risk, because it can slowly pull down your rankings. WordPress does tag comment links as nofollow, which limits the damage.

We hope this article helped you learn how to protect your WordPress website against spam. You may also want to check out our ultimate WordPress security guide to improve your website security.

If you liked this article, then please subscribe to our YouTube Channel for WordPress video tutorials. You can also find us on Twitter and Facebook.

The post Ultimate WordPress Spam Protection Guide – Step by Step (2026) first appeared on WPBeginner.

For years, the post editor has lived a double life. The Site Editor renders your blocks inside an iframe. The post editor — where most people actually spend their time — renders them directly in the admin page. That split ends with WordPress 7.1: the post editor canvas will always be an iframe, on every theme, no matter what apiVersion your blocks declare. The Gutenberg plugin has been enforcing exactly this for months. If you ship blocks, assume the iframe.

If your block never touches the global document or window, you can probably stop reading after you’ve changed "apiVersion": 2 to "apiVersion": 3 in block.json. For everyone else — and especially anyone shipping blocks that wrap third-party libraries — the iframe changes where your code runs versus where your markup lives. That gap is where things break.

Quick reference guide: Are your blocks ready?

The timeline, in one table

The WordPress 7.0 change is subtle but important: before 7.0, one apiVersion: 2 block registered by any active plugin — even one never used in the post — kept the entire editor out of the iframe for everyone. Now only inserted blocks count. Your v3 block gets the iframe until the user inserts a legacy one, at which point the editor quietly reloads the canvas without the iframe. The companion plugin ships a legacy-api-v2 block so you can watch this happen — insert it into an otherwise-v3 post and the iframe disappears. In 7.1, that escape hatch closes.

Worth knowing, as an aside: the “every theme” decision landed in WordPress 7.1 Beta 1, and it’s deliberately being tested in public. Gutenberg merged “Post editor: always iframe” (#74042) on July 10, 2026, deleting the theme and apiVersion conditions outright. The 7.1 release lead signed off on that merge on the condition that the team could “move to the softer approach” if Beta 1 feedback surfaced real problems — the softer approach being enforcement on block themes only, with everything else staying on the 7.0 rules. No specific mechanism is committed to; the plan is to respond to what the beta actually turns up.
Which is a reason to test harder, not to wait and see. If that rollback happens, the iframed and non-iframed editors both stay in the wild longer — and your block has to work in both regardless of which way it goes.

It’s also worth noting that blocks that will break with the 7.1 changes are most likely already breaking in the Site Editor.

Why the iframe is a good thing

This isn’t change for change sake. Rendering the canvas in an iframe gives the editor a real document boundary:

• Admin CSS stops leaking into your content. No more #wpadminbar-adjacent style resets, no more admin styles subtly changing how blocks render in the editor versus the front end.
• Viewport units and media queries finally work. vw, vh, and @media rules resolve against the canvas, not the admin page — so tablet/mobile previews and zoomed-out views actually behave like the front end.
• What you see is much closer to what you get. The canvas document is built from your theme’s styles, not the admin’s.

The issue this raises for block developers? Your editor JavaScript runs in the admin page, but your block’s DOM lives in a different document. Every assumption baked into document.querySelector(...) and window.addEventListener(...) just became wrong.

What actually breaks (and how to fix it)

Everything below is demonstrable with the companion plugin — each pattern ships as a broken/fixed pair of blocks: iframe-editor-examples on GitHub.

1. Global window and document references

The classic: a block that reads the viewport or listens for resize.

// <img decoding="async" alt="❌" class="wp-smiley" src="https://s.w.org/images/core/emoji/17.0.2/72x72/274c.png" /> Broken in the iframed editor
useEffect( () => {
	const update = () => setWidth( window.innerWidth );
	update();
	window.addEventListener( 'resize', update );
	return () => window.removeEventListener( 'resize', update );
}, [] );

// ❌ Broken in the iframed editor
useEffect( () => {
	const update = () => setWidth( window.innerWidth );
	update();
	window.addEventListener( 'resize', update );
	return () => window.removeEventListener( 'resize', update );
}, [] );

Editor scripts load in the admin page, so window is the admin window. In the iframed editor this reports the wrong width and never reacts to the canvas resizing — switch to the Tablet preview and the number doesn’t move.

The fix is to derive the document and window from your block’s own DOM element:

// <img decoding="async" alt="✅" class="wp-smiley" src="https://s.w.org/images/core/emoji/17.0.2/72x72/2705.png" /> Fixed — works iframed or not
import { useRefEffect } from '@wordpress/compose';

const ref = useRefEffect( ( element ) => {
	const { defaultView } = element.ownerDocument;
	const update = () => setWidth( defaultView.innerWidth );
	update();
	defaultView.addEventListener( 'resize', update );
	return () => defaultView.removeEventListener( 'resize', update );
}, [] );

const blockProps = useBlockProps( { ref } );

// ✅ Fixed — works iframed or not
import { useRefEffect } from '@wordpress/compose';

const ref = useRefEffect( ( element ) => {
	const { defaultView } = element.ownerDocument;
	const update = () => setWidth( defaultView.innerWidth );
	update();
	defaultView.addEventListener( 'resize', update );
	return () => defaultView.removeEventListener( 'resize', update );
}, [] );

const blockProps = useBlockProps( { ref } );

Two things to notice:

• element.ownerDocument is whatever document the block is rendered into — the iframe’s document when iframed, the admin document when not. ownerDocument.defaultView is that document’s window. Code written this way is context-agnostic: it doesn’t care whether the iframe exists.
• useRefEffect (from @wordpress/compose) instead of useRef + useEffect: it re-runs the callback when the ref changes, so if the block ever moves between documents, your listeners re-attach to the right window.

2. “Close on outside click” and other document-level events

This one is my favorite because it fails weirdly. A dropdown that closes when you click outside, implemented the way every React tutorial teaches it:

// <img decoding="async" alt="❌" class="wp-smiley" src="https://s.w.org/images/core/emoji/17.0.2/72x72/274c.png" /> Broken in the iframed editor
useEffect( () => {
	const closeOnOutsideClick = ( event ) => {
		if ( ! containerRef.current.contains( event.target ) ) {
			setIsOpen( false );
		}
	};
	document.addEventListener( 'click', closeOnOutsideClick );
	return () => document.removeEventListener( 'click', closeOnOutsideClick );
}, [] );

// ❌ Broken in the iframed editor
useEffect( () => {
	const closeOnOutsideClick = ( event ) => {
		if ( ! containerRef.current.contains( event.target ) ) {
			setIsOpen( false );
		}
	};
	document.addEventListener( 'click', closeOnOutsideClick );
	return () => document.removeEventListener( 'click', closeOnOutsideClick );
}, [] );

In the iframed editor, clicks inside the canvas happen in the iframe’s document. They never bubble to the admin document, so the listener never fires. The result: click another block in the canvas and the dropdown stays open — but click the admin sidebar and it closes. Same code, same block, works perfectly in the non-iframed editor. This is the kind of bug report you’ll get from users that “can’t be reproduced” — because whoever tested it happened to have a v2 block sitting in their post, which quietly dropped the iframe and made everything work.

Fix: same principle, attach to element.ownerDocument instead of document (see the plugin for the full useRefEffect version).

3. Editor styles enqueued into the wrong document

If you’re styling your block’s editor experience with enqueue_block_editor_assets, those styles load in the admin page — outside the iframe. They silently stop applying the moment the canvas is iframed:

// <img decoding="async" alt="❌" class="wp-smiley" src="https://s.w.org/images/core/emoji/17.0.2/72x72/274c.png" /> Loads in the admin page — never reaches the iframed canvas.
function myplugin_enqueue_editor_styles() {
	wp_enqueue_style( 'myplugin-editor', plugins_url( 'editor.css', __FILE__ ) );
}
add_action( 'enqueue_block_editor_assets', 'myplugin_enqueue_editor_styles' );

// ❌ Loads in the admin page — never reaches the iframed canvas.
function myplugin_enqueue_editor_styles() {
	wp_enqueue_style( 'myplugin-editor', plugins_url( 'editor.css', __FILE__ ) );
}
add_action( 'enqueue_block_editor_assets', 'myplugin_enqueue_editor_styles' );

The fix is to register editor styles through block.json, which WordPress injects into the canvas document, iframed or not:

{
	"editorStyle": "file:./index.css"
}

{
	"editorStyle": "file:./index.css"
}

(add_editor_style() also gets copied into the iframe, if you need theme-level editor styles.)

The demo plugin makes this visual: the same block carries a green banner from editorStyle and a red banner from enqueue_block_editor_assets. Count the banners — two means no iframe, one means you’re iframed.

4. Stale CSS written for the leaky editor

The section above is about CSS loading into the wrong document. This one is the sneakier inverse: the stylesheet loads into the right document — injected straight into the canvas, exactly as intended — and still gets it wrong, because of what it was written to describe. These are the rules that quietly stop matching, or start over-matching, once the canvas becomes its own document. It’s the code that’s been sitting in themes and plugins for years, “working,” right up until the iframe is enforced.

Selectors keyed on admin body classes

The most common one, and it fails exactly like the “close on outside click” bug — silently.

/* <img decoding="async" alt="❌" class="wp-smiley" src="https://s.w.org/images/core/emoji/17.0.2/72x72/274c.png" /> The canvas body no longer carries these classes */
.wp-admin .my-block { padding: 2rem; }
body.block-editor-page .my-block__title { font-size: 2rem; }

/* ❌ The canvas body no longer carries these classes */
.wp-admin .my-block { padding: 2rem; }
body.block-editor-page .my-block__title { font-size: 2rem; }

Inside the iframe, the canvas <body> is a clean document — no wp-admin, no block-editor-page. The selector matches nothing and your editor styling just evaporates. Same block, same stylesheet, works perfectly in the non-iframed editor.

/* <img decoding="async" alt="✅" class="wp-smiley" src="https://s.w.org/images/core/emoji/17.0.2/72x72/2705.png" /> Scope to the block, not the admin chrome */
.my-block { padding: 2rem; }
.my-block__title { font-size: 2rem; }

/* ✅ Scope to the block, not the admin chrome */
.my-block { padding: 2rem; }
.my-block__title { font-size: 2rem; }

.editor-styles-wrapper does still wrap the canvas content inside the iframe, so .editor-styles-wrapper .my-block keeps working if you need genuinely editor-only styling — but the admin ancestor was almost never necessary in the first place.

Offsets that compensate for admin chrome

/* <img decoding="async" alt="❌" class="wp-smiley" src="https://s.w.org/images/core/emoji/17.0.2/72x72/274c.png" /> Subtracting the admin sidebar and adminbar from the viewport */
.my-fullwidth { width: calc( 100vw - 160px ); } /* 160px = admin menu */
.my-toolbar   { position: fixed; top: 32px; }   /* 32px = #wpadminbar */

/* ❌ Subtracting the admin sidebar and adminbar from the viewport */
.my-fullwidth { width: calc( 100vw - 160px ); } /* 160px = admin menu */
.my-toolbar   { position: fixed; top: 32px; }   /* 32px = #wpadminbar */

This is the flip side of the win from earlier: now that 100vw resolves against the canvas instead of the admin page, there’s no sidebar to subtract — so the calc() overshoots, and top: 32px pushes your toolbar below an admin bar that doesn’t exist in this document.

/* <img decoding="async" alt="✅" class="wp-smiley" src="https://s.w.org/images/core/emoji/17.0.2/72x72/2705.png" /> The canvas is the viewport now — no compensation needed */
.my-fullwidth { width: 100vw; }
.my-toolbar   { position: fixed; top: 0; }

/* ✅ The canvas is the viewport now — no compensation needed */
.my-fullwidth { width: 100vw; }
.my-toolbar   { position: fixed; top: 0; }

Specificity walls built to fight leakage

/* <img decoding="async" alt="❌" class="wp-smiley" src="https://s.w.org/images/core/emoji/17.0.2/72x72/274c.png" /> Cranked up to beat leaking admin styles */
.editor-styles-wrapper .my-block p {
	font-family: Georgia, serif !important;
	line-height: 1.6 !important;
	box-sizing: border-box !important;
}

/* ❌ Cranked up to beat leaking admin styles */
.editor-styles-wrapper .my-block p {
	font-family: Georgia, serif !important;
	line-height: 1.6 !important;
	box-sizing: border-box !important;
}

The iframe already stops admin CSS from leaking in — that’s one of the reasons it’s a good thing. These !importants and resets have no admin styles left to override, but they do now override the theme styles the iframe loads into the canvas. The result: your editor preview drifts away from the front end — the exact opposite of what the iframe is for.

/* <img decoding="async" alt="✅" class="wp-smiley" src="https://s.w.org/images/core/emoji/17.0.2/72x72/2705.png" /> Let theme styles through; set only what your block truly owns */
.my-block p { font-family: Georgia, serif; }

/* ✅ Let theme styles through; set only what your block truly owns */
.my-block p { font-family: Georgia, serif; }

Two things to notice:

• The pattern is the same as the JavaScript fixes: stop describing the admin, start describing your block. A selector that names .wp-admin, #wpadminbar, or .block-editor-page is reaching for chrome that isn’t in the canvas document anymore.
• Most of these were workarounds for problems the iframe solves. Deleting them is usually the fix.

5. Third-party libraries that assume one global context

The biggest real-world hazard. Masonry layouts, sliders, lightboxes, maps — a generation of libraries was written assuming there is exactly one document:

// Inside some-legacy-lib.js
const targets = document.querySelectorAll( selector ); // finds nothing in the iframe

// Inside some-legacy-lib.js
const targets = document.querySelectorAll( selector ); // finds nothing in the iframe

Your block calls the library, the library queries the admin document, finds zero matches, and silently does nothing. No error, no warning — the block just stops being enhanced.

Your options, in order of preference:

• Pass elements, not selectors. If the library accepts an element (lib.init( element )), hand it the block’s element from useRefEffect and you’re usually fine.
• Patch the library. For unmaintained dependencies, patch-package is the pragmatic answer: edit the module in node_modules to resolve document/window from the element (node.ownerDocument), run npx patch-package <pkg>, commit the patch, add a postinstall script. The official migration guide walks through a real patch for @panzoom/panzoom.
• Guard and bail. If the library is loaded inside the iframe (front-end scripts are), check for it on defaultView before using it: if ( ! defaultView.jQuery ) return;

So what does apiVersion: 3 actually do?

Less than you might think — and that’s the point. Declaring "apiVersion": 3 in block.json doesn’t change how your block renders; it’s a signal that your block is iframe-ready. All core blocks have been on v3 since WordPress 6.3. For most blocks the migration is literally a one-line change… followed by the actual work: testing that nothing in your edit component (or the libraries it pulls in) touches the global document/window.

And to be clear about 7.1: the iframe will be enforced there regardless of apiVersion. Staying on v2 doesn’t opt you out anymore — it just means you get the console warning and the breakage.

How to test today

You don’t need to wait for 7.1. What you’re testing is that your block works in both states — iframed and not — because both will exist in the wild for a while yet.

Iframed: install the Gutenberg plugin 22.6+. It enforces the iframe regardless of theme, so this is the fastest way to live in the future. 7.1 Beta 1 does the same — I’ve confirmed it forces the iframe on a classic theme, which is the merged behavior shipping in August.

Not iframed: run WordPress 7.0 without the plugin and insert a v1/v2 block alongside yours — the canvas drops the iframe on the fly. The companion plugin’s legacy-api-v2 block exists for exactly this. Any theme will do: core 7.0 has no theme check in the iframe decision at all, so you don’t need to hunt down a classic theme to reproduce this.

Confirm which state you’re in: element.ownerDocument !== document, or look for iframe[name="editor-canvas"] in devtools.

The Site Editor has been iframed for years — if your block already behaves there, you’re most of the way home.

The companion plugin ships a wp-env setup, an example override file that adds Gutenberg for enforced mode (copy it to .wp-env.override.json), and two Playground blueprints — one per state, so you can flip between iframed and not in two tabs without installing anything.

The block author’s checklist

1. Set "apiVersion": 3 in every block.json.
2. Check your editor code for window. and document. — every hit is a suspect. Replace with element.ownerDocument / .defaultView via useRefEffect.
3. Check for enqueue_block_editor_assets — move canvas-affecting styles to editorStyle in block.json.
4. Check your editor CSS for .wp-admin, #wpadminbar, and .block-editor-page , admin chrome offsets and !important
5. Audit third-party libraries: pass elements not selectors, patch what you must.
6. Test both states, not both themes: iframed (Gutenberg 22.6+ active) and not iframed (no plugin, v1/v2 block inserted).
7. Watch the console with SCRIPT_DEBUG on — the deprecation warnings tell you which registered blocks are still on v1/v2.

Resources

• Iframed Editor Changes in WordPress 7.0 — the dev note this all builds on
• Post editor: always iframe (#74042) — the merged PR that makes 7.1 always-iframed, and the discussion behind the beta-feedback plan
• Roadmap to 7.1 — the original block-themes-first plan, superseded by #74042
• Preparing the Post Editor for Full iframe Integration — the 6.9 groundwork
• Migrating Blocks for iframe Editor Compatibility — the official migration guide
• Block API Versions — what each version means
• Enqueueing editor assets
• Editor styles for themes
• Companion demo plugin: iframe-editor-examples