Install
The quickest way is the generator: it writes the snippet for you. By hand, it's a config object and the SDK, placed first in <head>, before Google tags or any tracker:
<script>
window.CookieConsentConfig = {
siteId: 'my-site',
ui: { privacyPolicyUrl: '/privacy' },
};
</script>
<script src="sdk/0.4.0/cookie-consent.min.js"
integrity="sha384-gz2lwiJpLM5lcUGG9u1ITBnQaTT7Fz03qOXP8SkpEm3IEg1B4BV+tCXqmzFCMYjy" crossorigin="anonymous"></script>
The SDK URL is pinned to version 0.4.0, and the integrity hash makes the browser refuse the file if it was ever changed. To upgrade, generate a new snippet. You can also download cookie-consent.min.js and serve it from your own domain.
Block your tags until consent
About 35 common trackers (Google Analytics and Ads, Meta, TikTok, LinkedIn, Hotjar, Microsoft Clarity and UET, Pinterest, Snap, Reddit and more) are blocked automatically until the visitor allows their category. For anything else:
<!-- Scripts: type="text/plain" + a category -->
<script type="text/plain" data-cc-category="analytics" src="https://example.com/stats.js"></script>
<!-- Iframes: move src to data-cc-src -->
<iframe data-cc-category="functional" data-cc-src="https://www.youtube.com/embed/ID"></iframe>
<!-- Any element with data-cc-open reopens the settings -->
<a href="#" data-cc-open>Cookie settings</a>
<a href="#" data-cc-open>Do Not Sell or Share My Personal Information</a>
The categories are necessary (always on), functional, analytics and marketing. When a visitor withdraws consent, the cookies of that category are deleted and the page reloads, because scripts that already ran can't be stopped any other way.
Google tags and Google Tag Manager
With Consent Mode v2 on (the default), the SDK sets Google's consent defaults before your Google tag loads and sends an update when the visitor chooses. Keep your normal Google tag after the SDK, with no changes. In advanced mode Google tags load and send cookieless pings until consent; in basic mode they're blocked until consent.
With Google Tag Manager, load the SDK before the GTM container. A GTM tag template is included with the self-hosted server.
What visitors see
| Where | Model | Banner |
|---|---|---|
| EU, EEA, UK, Switzerland, Brazil, Quebec — and anywhere unlisted or unknown | Opt-in | Nothing optional runs until the visitor accepts. "Reject all" is as prominent as "Accept all". |
| California and 18 other US states with privacy laws | Opt-out | Runs by default, with "Do Not Sell or Share". Global Privacy Control is honoured automatically and confirmed to the visitor. |
| Other US states, the rest of Canada | Notice | An informational banner; preferences are still available. |
Location matters. With only the snippet, the SDK can recognise Europe, the UK and Switzerland from the visitor's time zone, but it can't tell US states apart. Visitors outside Europe are therefore treated as "unknown" and get the strict opt-in banner. That's safe, but it is stricter than US law requires.
To give US visitors the opt-out or notice experience, point geo.endpoint at a service that returns {"country":"US","region":"CA"}. The self-hosted server's /api/geo does this when it runs behind a CDN that adds location headers (Cloudflare, Vercel, CloudFront, Fastly and others). You can also adjust the rules, for example to make unknown visitors get a notice; see regionRules in the server's README.
JavaScript API
CookieConsent.ready // Promise, resolves once the banner is set up
CookieConsent.getConsent() // { decided, categories, jurisdiction, model, gpc, … }
CookieConsent.hasConsent('analytics') // true / false
CookieConsent.onConsent('analytics', fn) // run fn now, or as soon as allowed
CookieConsent.on('consent', fn) // also 'change', 'show', 'hide', 'ready'
CookieConsent.showPreferences() // open the settings
CookieConsent.reset() // forget the choice and ask again
Self-host the server
The snippet alone gives visitors a working banner. Run the included Node.js server (Node 22.13 or newer, no other dependencies) when you need:
- Proof of consent: a receipt for every choice, with export and retention controls.
- An admin app: edit the banner, categories, regions and texts with a live preview. Changes go live without touching your site.
- Team accounts: owner, admin, editor and viewer roles, per-site access for clients or agencies, and an audit log of every change.
- A cookie scanner: crawls your site in a headless browser, finds cookies set before consent, and suggests the categories.
- Accurate location from your CDN, and IAB TCF / GPP for programmatic advertising.
npm install
ADMIN_EMAIL=you@example.com ADMIN_PASSWORD='a long passphrase' npm start
# admin: http://localhost:3000/admin/
# embed: <script src="https://consent.example.com/c/<siteId>.js"></script>
It stores data in SQLite by default, or Postgres via DATABASE_URL. Put it behind HTTPS and set PUBLIC_URL, IP_SALT and TRUST_PROXY=1 when it sits behind a proxy. The server's README covers every setting.
IAB TCF and GPP
Sites that sell programmatic advertising in Europe usually need an IAB TCF v2 banner (Google requires a certified CMP for ads in the EEA and UK). The IAB build implements TCF v2.x and GPP for US states, plus Google Additional Consent. A TC string is only valid with a CMP ID that IAB Europe has assigned to you. Registration, validation and Google certification are steps you take with IAB Europe and Google; they can't be done in code. Until then, leave TCF off and the standard banner plus Consent Mode v2 covers Google's own tags.
Privacy
This website sets no analytics or advertising cookies and loads no third-party scripts. The banner on the home page stores your demo choice in a first-party cc_consent cookie so you can try it. The generator runs entirely in your browser, and nothing you type is sent anywhere. When you use the snippet, your visitors' browsers download the SDK file from this site. Like any web server, the host may keep standard access logs (IP address, time, user agent) for operation and security; no consent data from your visitors is sent here.
If you self-host the server, you are the controller of the consent receipts it stores. They hold a pseudonymous consent ID, the choices, the jurisdiction, and a salted hash of the IP address.