cookiebanner-finally
Advanced tools
Headless cookie banner library for Next.js with shadcn philosophy
A headless cookie consent management library for Next.js, built with the shadcn philosophy.
# Using npm
npm install cookiebanner-finally
# Using yarn
yarn add cookiebanner-finally
# Using pnpm
pnpm add cookiebanner-finally
# Using bun
bun add cookiebanner-finally
First, wrap your application with the ConsentProvider:
// app/providers.tsx
'use client'
import { ConsentProvider } from 'cookiebanner-finally';
export function Providers({ children }) {
return (
<ConsentProvider>
{children}
</ConsentProvider>
);
}
// app/layout.tsx
import { Providers } from './providers';
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<Providers>
{children}
</Providers>
</body>
</html>
);
}
// components/CookieBanner.tsx
'use client'
import { useCookieBanner, ConsentCategory } from 'cookiebanner-finally';
export function CookieBanner() {
const { isVisible, acceptAll, denyAll, close } = useCookieBanner();
if (!isVisible) return null;
return (
<div className="fixed bottom-0 left-0 right-0 bg-white p-4 shadow-lg border-t">
<div className="max-w-7xl mx-auto">
<h2 className="text-lg font-semibold">Cookie Consent</h2>
<p className="my-2">
We use cookies to enhance your browsing experience, serve personalized
ads or content, and analyze our traffic.
</p>
<div className="flex gap-2 mt-4">
<button
onClick={acceptAll}
className="bg-blue-600 text-white px-4 py-2 rounded"
>
Accept All
</button>
<button
onClick={denyAll}
className="bg-gray-200 px-4 py-2 rounded"
>
Reject Non-Essential
</button>
<button
onClick={close}
className="border px-4 py-2 rounded"
>
Close
</button>
</div>
</div>
</div>
);
}
// components/CookieSettings.tsx
'use client'
import { useCookiePreferences, ConsentCategory } from 'cookiebanner-finally';
export function CookieSettings() {
const { preferences, updateCategory } = useCookiePreferences();
return (
<div className="cookie-settings">
<h2 className="text-lg font-semibold mb-4">Cookie Settings</h2>
<div className="space-y-4">
<div className="flex items-start gap-2">
<input
type="checkbox"
id="necessary"
checked={preferences.necessary}
disabled={true}
className="mt-1"
/>
<div>
<label htmlFor="necessary" className="font-medium">Necessary Cookies</label>
<p className="text-sm text-gray-600">Required for the website to function properly.</p>
</div>
</div>
<div className="flex items-start gap-2">
<input
type="checkbox"
id="preferences"
checked={preferences.preferences}
onChange={(e) => updateCategory(ConsentCategory.Preferences, e.target.checked)}
className="mt-1"
/>
<div>
<label htmlFor="preferences" className="font-medium">Preference Cookies</label>
<p className="text-sm text-gray-600">Remember your settings and preferences.</p>
</div>
</div>
<div className="flex items-start gap-2">
<input
type="checkbox"
id="analytics"
checked={preferences.analytics}
onChange={(e) => updateCategory(ConsentCategory.Analytics, e.target.checked)}
className="mt-1"
/>
<div>
<label htmlFor="analytics" className="font-medium">Analytics Cookies</label>
<p className="text-sm text-gray-600">Help us improve by tracking anonymous usage data.</p>
</div>
</div>
<div className="flex items-start gap-2">
<input
type="checkbox"
id="marketing"
checked={preferences.marketing}
onChange={(e) => updateCategory(ConsentCategory.Marketing, e.target.checked)}
className="mt-1"
/>
<div>
<label htmlFor="marketing" className="font-medium">Marketing Cookies</label>
<p className="text-sm text-gray-600">Track your activity across websites to provide personalized ads.</p>
</div>
</div>
</div>
</div>
);
}
// components/AnalyticsLoader.tsx
'use client'
import { useEffect } from 'react';
import { useScriptLoader, ConsentCategory } from 'cookiebanner-finally';
export function AnalyticsLoader() {
const { register, load } = useScriptLoader();
useEffect(() => {
// Register scripts
register({
id: 'google-analytics',
category: ConsentCategory.Analytics,
src: 'https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX',
});
register({
id: 'ga-config',
category: ConsentCategory.Analytics,
content: `
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-XXXXXXXXXX');
`,
});
// Try to load scripts (only loads if consent is given)
load('google-analytics').then((loaded) => {
if (loaded) {
load('ga-config');
}
});
}, [register, load]);
return null;
}
// In your app/layout.tsx
// <AnalyticsLoader />
// components/YouTubeEmbed.tsx
'use client'
import { ConsentGate, ConsentCategory } from 'cookiebanner-finally';
export function YouTubeEmbed({ videoId }: { videoId: string }) {
return (
<ConsentGate
category={ConsentCategory.Marketing}
messages={{
consentRequired: 'This YouTube video requires consent for {category} cookies to load.',
managePreferences: 'Allow YouTube Videos',
loading: 'Loading video...'
}}
>
<iframe
width="560"
height="315"
src={`https://www.youtube.com/embed/${videoId}`}
title="YouTube video player"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
/>
</ConsentGate>
);
}
The ConsentGate component supports customizable messages for better user experience:
<ConsentGate
category={ConsentCategory.Analytics}
messages={{
consentRequired: 'This content requires consent for {category} cookies.',
managePreferences: 'Manage Cookie Settings',
loading: 'Loading content...'
}}
>
{/* Your protected content */}
</ConsentGate>
Message Options:
consentRequired: Message shown when consent is needed. Use {category} as a placeholder for the consent category.managePreferences: Button text for opening consent preferences.loading: Loading message displayed while checking consent status.Default Messages:
consentRequired: "This content requires consent for {category} cookies."managePreferences: "Manage Cookie Preferences"loading: "Loading..."'use client'
import { ConsentProvider, ConsentCategory } from 'cookiebanner-finally';
export function Providers({ children }) {
return (
<ConsentProvider
cookieName="my-app-consent"
cookieExpires={180} // Days
initialPreferences={{
[ConsentCategory.Analytics]: true, // Pre-select analytics
}}
autoShowBanner={true}
>
{children}
</ConsentProvider>
);
}
You can integrate analytics providers like PostHog while respecting user consent preferences using the ConsentGate component:
// components/PostHogGateProvider.tsx
'use client'
import React from 'react';
import { ConsentGate, ConsentCategory } from 'cookiebanner-finally';
import { PostHogProvider } from '@posthog/nextjs/react';
export function PostHogGateProvider({
children,
apiKey = 'YOUR_API_KEY',
apiHost = 'https://app.posthog.com'
}) {
return (
<ConsentGate
category={ConsentCategory.Analytics}
fallback={<>{children}</>} // Just render children without PostHog
>
{/* Only rendered when analytics consent is given */}
<PostHogProvider
apiKey={apiKey}
options={{
api_host: apiHost,
}}
>
{children}
</PostHogProvider>
</ConsentGate>
);
}
Then in your providers.tsx:
// app/providers.tsx
'use client'
import { ConsentProvider } from 'cookiebanner-finally';
import { PostHogGateProvider } from '../components/PostHogGateProvider';
export function Providers({ children }) {
return (
<ConsentProvider>
<PostHogGateProvider>
{children}
</PostHogGateProvider>
</ConsentProvider>
);
}
When using PostHog in client components:
'use client'
import { usePostHog } from 'posthog-js/react';
import { useCookiePreferences, ConsentCategory } from 'cookiebanner-finally';
export function AnalyticsAwareButton() {
const { preferences } = useCookiePreferences();
const posthog = usePostHog();
const handleClick = () => {
// Safe to use - if PostHog isn't available (no consent),
// we check before usage
if (preferences.analytics && posthog) {
posthog.capture('button_clicked');
}
// Always execute this part regardless of consent
console.log('Button clicked');
};
return (
<button onClick={handleClick}>
Track Event
</button>
);
}
'use client'
import { useEffect, useState } from 'react';
import { useConsentGate, ConsentCategory } from 'cookiebanner-finally';
export function useMapEmbed() {
const { hasConsent, showConsentPrompt } = useConsentGate(ConsentCategory.Marketing);
const [mapLoaded, setMapLoaded] = useState(false);
useEffect(() => {
if (hasConsent && !mapLoaded) {
// Initialize map when consent is given
const script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY';
script.onload = () => setMapLoaded(true);
document.head.appendChild(script);
}
}, [hasConsent, mapLoaded]);
return {
canShowMap: hasConsent && mapLoaded,
requestConsent: showConsentPrompt,
};
}
This library is built with TypeScript and provides full type definitions for all components, hooks, and utility functions.
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License
Copyright (c) 2025 Samuel Lembke
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
FAQs
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Socket detected malicious node-ipc versions with obfuscated stealer/backdoor behavior in a developing npm supply chain attack.
Security News
TeamPCP and BreachForums are promoting a Shai-Hulud supply chain attack contest with a $1,000 prize for the biggest package compromise.
Security News
Packagist urges PHP projects to update Composer after a GitHub token format change exposed some GitHub Actions tokens in CI logs.