@scthakuri/adblock-detector

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.

Demo

Live demo: try it yourself

Open the demo, enable an adblock extension in your browser, then reload the page. The detector modal appears live.

Features

• ✅ Zero runtime dependencies. No crypto-js, no polyfills, nothing else installed alongside React.
• ✅ Detects most popular adblock extensions (see Tested With)
• ✅ 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. No bundled crypto library; class-name obfuscation uses a tiny inline hash instead.

Installation

# npm
npm i @scthakuri/adblock-detector

# yarn
yarn add @scthakuri/adblock-detector

# pnpm
pnpm add @scthakuri/adblock-detector

Requires React ≥16.8 (uses hooks internally).

Quick Start

Simplest usage, detects and shows the modal automatically:

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

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

export default App;

If you need to control visibility yourself (custom trigger logic, analytics on detection, etc.), use the hook and DetectorModal directly:

import { useState } from 'react';
import DetectorModal, { useAdblockDetector } from '@scthakuri/adblock-detector';

function App() {
  const { detected } = useAdblockDetector();
  const [dismissed, setDismissed] = useState(false);

  return (
    <div className="App">
      {detected && !dismissed && (
        <DetectorModal
          closeBtn
          onModalClose={() => setDismissed(true)}
        />
      )}
    </div>
  );
}

export default App;

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, minus needing onModalClose (it's handled internally, though you can still pass one for a side effect on close).

<AutoDetectorModal closeBtn theme="#4f46e5" />

useAdblockDetector()

React hook: the recommended way to consume detection state. Runs the check once on mount and is unmount-safe (won't call setState after the component using it is gone).

| Returns | Type | Description | |---|---|---| | detected | boolean | Whether an adblocker was detected. | | loading | boolean | true until the check resolves. |

const { detected, loading } = useAdblockDetector();

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.

| Param | Type | Description | |---|---|---| | callback | (detected: boolean) => void | Called once with the detection result. |

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

detectAdblock((detected) => {
  if (detected) {
    // an adblocker is active
  }
});

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 (e.g. skip the fair-adblock check, or add your own probes alongside it).

| Param | Type | Description | |---|---|---| | callback | (detected: boolean) => void | Called once with the detection result. |

DetectAdblock / DetectByGoogleAd (PascalCase) remain exported as deprecated aliases for existing code. New code should use the camelCase names above.

<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 (see Quick Start above).

| Prop | Type | Default | Description | |---|---|---|---| | theme | string | "#ff0000" | Any valid CSS color. Accents the icon, border, and footer. | | title | string | "Adblock Detected!!!" | Modal heading. | | message | string | (default message) | Modal body text. | | reloadBtnText | string | "I've Disable Adblock" | Text for the reload button. | | closeBtn | boolean | false | Show 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. |

<DetectorModal
  theme="#4f46e5"
  title="Please disable your ad blocker"
  message="This site is supported by ads. Please whitelist us to continue."
  reloadBtnText="Refresh page"
  closeBtn
  onModalClose={() => setDismissed(true)}
/>

Tested With

• ☞ Adblock Plus
• ☞ Adblock
• ☞ Adguard
• ☞ Adremover
• ☞ Adblock for Chrome™
• ☞ Brave
• ☞ Ghostery
• ☞ uBlocker
• ☞ uBlock
• ☞ Ultrablock
• ☞ Privacy Badger
• ☞ DuckDuckGo
• ☞ Disconnect
• ☞ Microsoft Edge AdBlock extension
• ☞ Firefox Tracking Protection
• ☞ uBlock Origin
• ☞ Fair AdBlocker
• ☞ Hola ad remover
• ☞ Comodo AdBlocker
• ☞ Opera Built-in AdBlock extension

Local Development

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:

npx tsc --noEmit

Contributing

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

License

MIT © Suresh Chand