Back to CHP Adblock

Docs & demo

Lightweight, dependency-free adblock detector for React. Detects most adblock extensions (uBlock Origin, AdBlock Plus, AdGuard, Brave's built-in blocker, and more) and gives you a ready-made, customizable modal to prompt visitors to disable them.

Enable an adblock extension, then try each pattern below - everything here runs the real published @scthakuri/adblock-detector package.

Star on GitHubnpm packagegithub.com/scthakuri/react-adblock-detector
npm versionnpm downloadsTypeScriptMIT License

AutoDetectorModal

Zero-config - detects on mount and shows the modal automatically. No state, no effect, just drop it in.

tsx
import { AutoDetectorModal } from '@scthakuri/adblock-detector';

function App() {
  return (
    <div className="App">
      <AutoDetectorModal closeBtn />
    </div>
  );
}

Installation

Requires React ≥16.8 (uses hooks internally).

bash
npm i @scthakuri/adblock-detector

Features

  • Zero runtime dependencies - no crypto-js, no polyfills, nothing else installed alongside React
  • Detects most popular adblock extensions (see Tested With below)
  • Ships a ready-made, themeable modal component, or use the raw detection function and build your own UI
  • Fully typed (.d.ts included, no @types package needed)
  • Small footprint - class-name obfuscation uses a tiny inline hash instead of a bundled crypto library

API Reference

<AutoDetectorModal />

Combines useAdblockDetector and DetectorModal into one drop-in component: detects on mount, renders nothing while loading or when no adblocker is found, and shows the modal automatically otherwise. Dismissing it (via closeBtn) hides it for the rest of the session. Accepts the same props as DetectorModal below.

useAdblockDetector()

React hook - the recommended way to consume detection state. Runs the check once on mount and is unmount-safe.

ReturnsTypeDescription
detectedbooleanWhether an adblocker was detected.
loadingboolean"true" until the check resolves.

detectAdblock(callback)

Imperative version of the same check, for use outside React (vanilla JS, class components, one-off checks). useAdblockDetector is built on top of this.

ParamTypeDescription
callback(detected: boolean) => voidCalled once with the detection result.

detectByGoogleAd(callback)

Lower-level probe used internally by detectAdblock. Checks connectivity, requests a real Google Ads script, and inspects both the network response and whether the global it sets survives. Exported in case you want to compose your own detection flow.

<DetectorModal />

Pre-built modal shown when an adblocker is detected. The component always renders its markup, so mount/unmount it based on your own detection state.

PropTypeDefaultDescription
themestring"#ff0000"Any valid CSS color. Accents the icon, border, and footer.
titlestring"Adblock Detected!!!"Modal heading.
messagestring(default message)Modal body text.
reloadBtnTextstring"I've Disable Adblock"Text for the reload button.
closeBtnbooleanfalseShow a close (×) button.
onModalClose() => void() => {}Called when the close button is clicked. The modal does not unmount itself; call this to update your own state.

Tested With

Adblock PlusAdblockAdguardAdremoverAdblock for Chrome™BraveGhosteryuBlockeruBlockUltrablockPrivacy BadgerDuckDuckGoDisconnectMicrosoft Edge AdBlock extensionFirefox Tracking ProtectionuBlock OriginFair AdBlockerHola ad removerComodo AdBlockerOpera Built-in AdBlock extension

Local Development

bash
git clone https://github.com/scthakuri/react-adblock-detector.git
cd react-adblock-detector
npm install       # also runs the build via the `prepare` script
npm run build      # compile src/ -> lib/

Type-check without emitting:

bash
npx tsc --noEmit

Contributing

Issues and PRs welcome at github.com/scthakuri/react-adblock-detector.

License

MIT © Suresh Chand

Links