@mmargauxx/cookie-banner
v0.1.0
Published
Tiny, framework-agnostic cookie consent banner (vanilla JS + Tailwind). Configurable copy, classes, and callbacks; returns open/close/reset handles.
Downloads
21
Maintainers
mmargauxxReadme
@mmargauxx/cookie-banner
A tiny, framework-agnostic cookie consent banner in vanilla JS/TS, styled with Tailwind. Everything is configurable — copy, links, callbacks, and the classes on every element — and initCookieBanner returns { open, close, reset } handles so you can re-open it later (e.g. from a footer "cookie settings" link) without relying on a global.
- No runtime dependencies. ~1 kB.
- Consent-Mode-v2 friendly. You decide what
onAcceptenables. - Themeable. Stock Tailwind palette defaults; override any class.
- Typed. Ships ESM + CJS +
.d.ts.
npm install @mmargauxx/cookie-bannerUsage
import { initCookieBanner } from '@mmargauxx/cookie-banner';
const banner = initCookieBanner({
text: 'We use analytics cookies to improve your visit.',
policyHref: '/cookies',
acceptLabel: 'Accept',
declineLabel: 'Decline',
onAccept: enableAnalytics,
});
// re-open from a footer link / policy page:
footerLink.addEventListener('click', banner.open);The banner mounts itself to document.body, and only opens automatically when no decision has been stored yet. The choice is saved to localStorage under storageKey.
Options
| Option | Type | Default |
| --- | --- | --- |
| onAccept | () => void \| null | null |
| onDecline | () => void \| null | null |
| storageKey | string | 'cookie_consent' |
| text | string (HTML allowed) | 'We use analytics cookies to improve your visit.' |
| policyHref | string \| null | '/cookies' — pass null/'' to omit the link |
| policyLabel | string | 'Learn more' |
| acceptLabel | string | 'Accept' |
| declineLabel | string | 'Decline' |
| classes | Partial<CookieBannerClasses> | stock Tailwind (see below) |
Returns — CookieBannerHandle
| Handle | Effect |
| --- | --- |
| open() | Show the banner. |
| close() | Hide the banner. |
| reset() | Clear the stored decision and re-open. |
createCookieBanner(opts) → string
Also exported: returns the banner's HTML as a string (no DOM side effects) if you want to control where/when it's inserted, or render it server-side.
Styling
The defaults use stock Tailwind palette classes (slate / emerald), so the banner looks right in any project that runs Tailwind. Override any subset:
initCookieBanner({
classes: {
accept: 'flex-1 bg-indigo-600 text-white hover:bg-indigo-700 px-5 py-2.5 rounded-full text-sm font-medium cursor-pointer',
// wrapper, text, link, actions, decline are kept at their defaults
},
});Overridable keys: wrapper, text, link, actions, decline, accept.
⚠️ Tailwind purging. The classes live inside this package's JS, so Tailwind won't see them when scanning your source and will purge them. Add the package to your
contentglobs:// tailwind.config.js export default { content: [ './src/**/*.{html,js,ts,jsx,tsx}', './node_modules/@mmargauxx/cookie-banner/dist/**/*.js', ], };If you override all the classes with your own (already-scanned) utilities, this isn't needed. Not using Tailwind at all? Pass your own
classes, or your own plain CSS class names and ship the CSS yourself.
Wiring up analytics (Consent Mode v2)
Two pieces live in your app, not in this package.
1. Set the Consent Mode v2 default in your document <head>, before GA loads, so Google respects consent from the first paint:
<script>
window.dataLayer = window.dataLayer || [];
function gtag() { dataLayer.push(arguments); }
gtag('js', new Date());
gtag('consent', 'default', {
ad_storage: 'denied', ad_user_data: 'denied',
ad_personalization: 'denied', analytics_storage: 'denied',
wait_for_update: 500,
});
gtag('config', 'G-XXXX', { send_page_view: false });
</script>2. Flip consent on accept (and re-enable on return visits):
import { initCookieBanner } from '@mmargauxx/cookie-banner';
import Clarity from '@microsoft/clarity';
function enableAnalytics() {
if (typeof window.gtag === 'function') {
window.gtag('consent', 'update', { analytics_storage: 'granted' });
}
Clarity.init('YOUR_CLARITY_ID');
}
if (localStorage.getItem('cookie_consent') === 'accepted') enableAnalytics();
initCookieBanner({ onAccept: enableAnalytics });Development
npm install
npm run example # vite demo at http://localhost:5173
npm run build # dist/ (esm + cjs + d.ts) via tsup
npm run typecheck
npm test # vitest (jsdom)Publishing
npm run build
npm publish # scoped package; publishConfig.access is already "public"License
MIT