Description
Over 40% of internet users run an ad blocker. Tiny Simple AdBlock Detector gives you the power to respond — politely ask visitors to whitelist your site, gate premium content, or simply track awareness — all without touching a line of JavaScript yourself.
How it works
The plugin loads a tiny decoy script with a filename that ad blockers love to block. When the script gets blocked, a lightweight CSS class swap kicks in — revealing or hiding any element you’ve marked up. That’s it. No jQuery, no external services, no tracking pixels, no cookie banners.
Two CSS classes. Infinite possibilities.
class="show-only-when-adblock"— Element appears only when an ad blocker is active.class="hide-only-when-adblock"— Element disappears when an ad blocker is active.
Add them to any HTML element: a <div>, a Gutenberg block, an Elementor section, a WooCommerce notice — anything.
Real-world examples
- “Please whitelist us” — Show a polite banner only to ad-blocking visitors
- Content gating — Hide exclusive articles or downloads from users blocking your ads
- Alternative monetization — Show a “Support us on Patreon” box only when ads are blocked
- Analytics — Pair with your analytics tool to track ad-blocker adoption rates on your site
Why this plugin?
- Zero configuration — Activate it and it works. No settings page, no wizard, no API key.
- Ridiculously lightweight — Under 2 KB of JavaScript. Your visitors won’t notice.
- No external requests — Nothing leaves your server. Fully GDPR-friendly.
- Works with all major ad blockers — uBlock Origin, AdBlock Plus, AdBlock, AdGuard, Brave Shield, Opera built-in blocker.
- Page builder compatible — Works with Gutenberg, Elementor, Divi, WPBakery, Beaver Builder — anything that lets you add a CSS class.
- Built-in debug mode — Append
?tsad_debug=1to any URL to see live detection results. - Translation-ready — Includes Polish translation. PRs welcome for others.
From the maker of WP Multi Tool
This plugin is built by the same developer behind WP Multi Tool — the Swiss Army knife for WordPress developers and site administrators. If you manage multiple WordPress sites, check it out.
Screenshots
Zero-config admin page — plugin works immediately after activation 
Built-in debug mode showing real-time ad blocker detection on the frontend
Installation
- Install through the WordPress plugin directory, or upload to
/wp-content/plugins/. - Activate the plugin. That’s it — it’s already running.
- Add
class="show-only-when-adblock"orclass="hide-only-when-adblock"to any HTML element. - (Optional) Visit the plugin’s admin page for a quick reference and debug link.
FAQ
-
Which ad blockers does it detect?
-
Tested and confirmed with: uBlock Origin, AdBlock Plus, AdBlock, AdGuard, Brave Shield, and Opera’s built-in blocker. It works by exploiting how ad blockers filter script filenames — so it catches most blockers that follow standard filter lists.
-
Does it slow down my site?
-
No. The total JavaScript payload is under 2 KB (two tiny files), loaded asynchronously. It makes zero external HTTP requests. Your PageSpeed score won’t budge.
-
Is it GDPR compliant?
-
Yes. The plugin doesn’t collect, store, or transmit any user data. It doesn’t set cookies, fingerprint browsers, or phone home. It’s pure client-side CSS class toggling.
-
How do I test if it’s working?
-
Append
?tsad_debug=1to any page on your site. A debug panel will appear at the bottom showing detection status in real-time. You can also find this link on the plugin’s admin page. -
Can I use it with Elementor / Gutenberg / page builders?
-
Absolutely. Just add the CSS class in your page builder’s “Advanced” “CSS Classes” field. Works with Gutenberg, Elementor, Divi, WPBakery, Beaver Builder, and any builder that supports custom CSS classes.
-
What if someone uses a blocker you don’t detect?
-
The detection relies on ad blockers blocking scripts with “ad-like” filenames (like
showads.js). Very aggressive blockers or custom filter lists will definitely get caught. Very minimal or niche blockers might slip through — but those cover a tiny fraction of users. -
Can I style the elements differently instead of show/hide?
-
The plugin uses
display: noneanddisplay: initialby default. You can override this in your own CSS by targeting.show-only-when-adblockand.hide-only-when-adblockwith higher specificity.
Reviews
There are no reviews for this plugin.
Contributors & Developers
“Tiny Simple AdBlock Detector” is open source software. The following people have contributed to this plugin.
Contributors
Translate “Tiny Simple AdBlock Detector” into your language.
Interested in development?
Browse the code, check out the SVN repository, or subscribe to the development log by RSS.
Changelog
1.2.0
- Tested and verified with WordPress 7.0
- Fixed hardcoded localhost URL in admin page — now uses dynamic site URL
- Added proper version strings to enqueued scripts for cache busting
- Updated plugin headers (Requires PHP, Requires at least)
- Completely rewritten readme with real-world usage examples
- Added plugin icon and banner
- Added screenshots
- Code cleanup: removed broken .min.js references
1.1.0
- Tested the functionality with the latest version of WordPress
- Improved the UI
- Added more complex testing
1.0.1
- Fixed the bug with the styling for class=”hide-only-when-adblock”
1.0.0
- Initial release