Developer documentation
The Nodbar script shows the banner, holds analytics and advertising tools back until the visitor consents, and keeps a proof of every choice. This page explains how your code plugs into it: tags to mark, JavaScript API, events, TypeScript types and examples for React, Vue and Next.js.
Install the script
Create your banner from your site’s address: the dashboard gives you the exact line, with the site’s key. Put it first in <head>, without async or defer: it must run before the other scripts to be able to hold them back.
<head> <script src="https://cdn.nodbar.com/s/YOUR-KEY.js"></script> <!-- your other scripts after it --> </head>
The WordPress, Shopify, PrestaShop, Joomla, Drupal and Magento plugins, and the Google Tag Manager template, add this line for you. Your coding assistant (Claude Code, Cursor…) can install it too: the dashboard’s Go live page gives it the full instructions.
The banner speaks the page’s language (the lang attribute of <html>), otherwise the browser’s, among your banner’s languages. If your application switches language without reloading the page, updatedocument.documentElement.lang: the banner, the cookie list and the video placeholders follow at once, and the visitor’s choice is recorded in their new language.
If your site sends a content security policy (Content-Security-Policy header), addhttps://cdn.nodbar.com to script-src (the script) and to connect-src(sending the consent proof). The banner does not need 'unsafe-inline' in style-src: it keeps its look under a strict, nonce- or hash-based policy.
Automatic or manual blocking
By default, Nodbar blocks the tools it knows on its own (scripts, pixels, iframes, cookies) until their category is accepted. The dashboard setting “Who blocks tools before consent?” also offers a manual mode: Nodbar no longer blocks anything on its own, and only the tags marked below and the code passed to Nodbar.when wait for consent. Google Consent Mode, the proofs and the banner stay the same. Either way, the scan of your site checks that nothing fires before consent.
Marking tags
Even with automatic blocking, the browser downloads a <script src> written in the HTML before any JavaScript runs, and an <iframe src> contacts its service straight away. Mark them: nothing goes out before consent, and Nodbar starts them the moment the visitor accepts.
Scripts: type="text/plain" and data-nodbar with the category, analytics,marketing or functional. Do not mark scripts the site needs (payment, cart, security).
<script type="text/plain" data-nodbar="analytics"
src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
<script type="text/plain" data-nodbar="marketing">
fbq('init', '123456789')
</script>Iframes (videos, maps, widgets): rename src to data-nodbar-src. Nodbar finds the service and its category from the address and shows an “Accept and show” placeholder in its place, at the same size. For a service it does not know, add data-nodbar; without it, the iframe loads straight away.
<iframe data-nodbar-src="https://www.youtube-nocookie.com/embed/VIDEO" width="560" height="315" title="Our video"></iframe> <!-- A service Nodbar does not know: give the category --> <iframe data-nodbar-src="https://widget.example.com/map" data-nodbar="functional"></iframe>
JavaScript API
The script exposes window.Nodbar:
| Method | What it does |
|---|---|
when(category, fn) | Runs fn once: right away if the category is accepted, otherwise the moment the visitor accepts it. An error in fn is logged to the console without affecting the others. Returns a function that cancels fn as long as it has not run. |
onChange(fn) | Calls fn with the granted categories after each choice, and on load when a choice is already stored, if fn is registered while the script starts (or through the queue snippet). Returns a function that unregisters fn, to call when your component unmounts. |
getConsent() | The granted categories, necessary included. |
getConsentId() | The identifier of the visitor’s consent proof, once they have chosen: give it to them if they ask. |
open() | Opens the preferences panel, for your own “Manage cookies” button. |
The categories are necessary (always granted), analytics, marketing andfunctional. When the visitor withdraws consent, the page reloads: a script that has already started cannot be stopped.
Start a tool loaded by your code
A tool installed from npm or started by your application has no tag to mark: wrap its initialisation inNodbar.when.
Nodbar.when('analytics', () => {
// runs once, after the visitor consents
posthog.init('phc_XXXXXXXX', { api_host: 'https://eu.i.posthog.com' })
})Call the API before the script loads
If your code can run before the Nodbar script (a script loaded by Google Tag Manager, asynchronous loading), add this line first: when, onChange and open are queued, then run as soon as the script starts. The cancel functions they return work both before and after it starts.
<script>window.Nodbar=window.Nodbar||{q:[]};['when','onChange','open'].forEach(function(m){Nodbar[m]=Nodbar[m]||function(){var e=[m].concat([].slice.call(arguments));Nodbar.q.push(e);return function(){typeof e.off=='function'?e.off():e.off=1}}})</script>“Manage cookies” link and cookie list
Any element with data-nodbar-open opens the preferences, even when your framework adds it later. On a page that shows such a link, the small button at the bottom of the screen no longer appears after the choice: the link replaces it. Adata-nodbar-cookies element, on your cookie policy page, fills with the list of the site’s cookies, up to date with every publication.
<a href="#" data-nodbar-open>Manage cookies</a> <div data-nodbar-cookies></div>
Events
After each choice, and on page load when a choice is already stored, the script dispatches thenodbar:consent event on window and pushes nodbar_consent to the Google Tag Manager data layer.
window.addEventListener('nodbar:consent', (event) => {
console.log(event.detail.granted) // ['necessary', 'analytics']
})
// Google Tag Manager: "Custom Event" trigger nodbar_consent,
// data layer variable nodbar_granted
window.dataLayer.push({ event: 'nodbar_consent', nodbar_granted: ['necessary', 'analytics'] })With nothing to add, the script also passes the choice to Google Consent Mode v2, Microsoft Clarity, Microsoft Ads, the Meta pixel, Matomo, Shopify’s Customer Privacy API and WordPress’s WP Consent API.
TypeScript types
Download nodbar.d.ts into your project, in a folder covered by theinclude of your tsconfig.json: window.Nodbar, its categories (NodbarCategory) and the nodbar:consent event are then typed.
curl -o src/nodbar.d.ts https://nodbar.com/nodbar.d.ts
window.Nodbar is undefined until the script has started, hence the ?. in the examples. With the queue snippet, only when, onChange and open exist before it starts.
React, Vue and Next.js examples
React
// useConsent.ts: the granted categories, updated on every choice
import { useEffect, useState } from 'react'
export function useConsent(): NodbarCategory[] {
const [granted, setGranted] = useState<NodbarCategory[]>(['necessary'])
useEffect(() => {
const update = (event: CustomEvent<NodbarConsentDetail>) => setGranted(event.detail.granted)
window.addEventListener('nodbar:consent', update)
const current = window.Nodbar?.getConsent?.()
if (current) setGranted(current)
return () => window.removeEventListener('nodbar:consent', update)
}, [])
return granted
}
// Analytics.tsx: starts a tool installed from npm, once, after consent
import { useEffect } from 'react'
import posthog from 'posthog-js'
export function Analytics() {
// when returns a cancel function: if the component unmounts before consent,
// posthog.init is never called
useEffect(() => window.Nodbar?.when('analytics', () => posthog.init('phc_XXXXXXXX')), [])
return null
}
// Footer
<button type="button" data-nodbar-open>Manage cookies</button>Vue
// useConsent.ts
import { onMounted, onUnmounted, ref } from 'vue'
export function useConsent() {
const granted = ref<NodbarCategory[]>(['necessary'])
const update = (event: CustomEvent<NodbarConsentDetail>) => {
granted.value = event.detail.granted
}
onMounted(() => {
window.addEventListener('nodbar:consent', update)
granted.value = window.Nodbar?.getConsent?.() ?? granted.value
})
onUnmounted(() => window.removeEventListener('nodbar:consent', update))
return granted
}
// main.ts: a tool started by the application
window.Nodbar?.when('analytics', () => {
/* start the tool */
})Next.js
Do not use next/script with afterInteractive or lazyOnload: the script would arrive too late to hold the others back.
// app/layout.tsx: the Nodbar script first, without next/script
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<head>
<script src="https://cdn.nodbar.com/s/YOUR-KEY.js" />
</head>
<body>{children}</body>
</html>
)
}
// app/analytics.tsx: client component, mounted in the layout
'use client'
import { useEffect } from 'react'
export function Analytics() {
useEffect(
() =>
window.Nodbar?.when('analytics', () => {
/* start the tool */
}),
[],
)
return null
}Appearance
Colours, fonts and corner radii are set in the dashboard. Your stylesheet can also override them with CSS variables, and target each part of the banner with ::part().
nodbar-consent {
--nodbar-primary: #0b5cff;
--nodbar-button-radius: 0;
}
nodbar-consent::part(button-accept) {
letter-spacing: 0.02em;
}Variables: --nodbar-primary, --nodbar-on-primary, --nodbar-background, --nodbar-text, --nodbar-radius, --nodbar-button-radius, --nodbar-font, --nodbar-heading-font, --nodbar-font-size, --nodbar-button-weight, --nodbar-button-case, --nodbar-shadow.
Parts: panel, banner, preferences, title, body, actions, button, button-reject, button-accept, button-save, link, category, toggle, always-on, close, reopen, backdrop, meta.
Get started
Paste your site’s address: Nodbar scans it and prepares a compliant banner, for free.