Tiny, frontend-only consent gating for Next.js and React apps.
OpenCookie helps developers block analytics, pixels, widgets, and other optional components until the user gives consent. It has no backend, no dashboard, no telemetry, and no hosted API.
OpenCookie helps implement consent-gated loading. It does not provide legal advice or guarantee compliance.
Try the live demo: blodyle.github.io/opencookie
yarn add @opencookie/reactAdd the provider and default banner:
// app/layout.tsx
import { OpenCookieBanner, OpenCookieProvider } from "@opencookie/react"
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<OpenCookieProvider>
{children}
<OpenCookieBanner />
</OpenCookieProvider>
</body>
</html>
)
}config is optional. When no config is passed, OpenCookie uses the built-in categories:
necessary, required and always grantedanalyticsmarketingpreferences
Before the user chooses, optional categories are denied by default.
Create open-cookie.config.ts when you want to customize categories, labels, descriptions, versioning, storage, or Google Consent Mode mapping.
defineOpenCookieConfig is optional too. It gives you typed defaults and a clear place for coding agents to inspect consent behavior.
// open-cookie.config.ts
import { defineOpenCookieConfig } from "@opencookie/react/config"
export const openCookieConfig = defineOpenCookieConfig({
version: "1",
categories: [
{ id: "necessary", label: "Necessary", required: true },
{ id: "analytics", label: "Analytics" },
{ id: "marketing", label: "Marketing" },
],
googleConsent: {
enabled: true,
},
})Then pass it to the provider:
// app/layout.tsx
import { OpenCookieBanner, OpenCookieProvider } from "@opencookie/react"
import { openCookieConfig } from "../open-cookie.config"
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<OpenCookieProvider config={openCookieConfig}>
{children}
<OpenCookieBanner />
</OpenCookieProvider>
</body>
</html>
)
}Gate analytics or any optional child:
import { OpenCookieGate } from "@opencookie/react"
export function Analytics() {
return (
<OpenCookieGate category="analytics">
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXX" />
</OpenCookieGate>
)
}OpenCookieGate requires a category. This keeps gated scripts and components explicit:
<OpenCookieGate category="marketing">
<iframe src="https://www.youtube.com/embed/example" />
</OpenCookieGate>The default banner can stay calm or use a lighter tone:
<OpenCookieBanner tone="playful" />The default banner is optional. Build your own UI with useOpenCookie, or start with the custom banner recipe:
"use client"
import { useOpenCookie } from "@opencookie/react"
export function CookieBanner() {
const consent = useOpenCookie()
if (!consent.shouldShowBanner) return null
return (
<div>
<p>We use optional cookies for analytics.</p>
<button onClick={consent.rejectAll}>Reject</button>
<button onClick={consent.acceptAll}>Accept all</button>
</div>
)
}When googleConsent.enabled is true, OpenCookie writes Google Consent Mode commands to window.dataLayer.
Before a saved choice exists, optional Google storage signals are denied. After consent is saved, OpenCookie sends an update based on the saved categories.
Default mapping:
| Google signal | OpenCookie category |
|---|---|
analytics_storage |
analytics |
ad_storage |
marketing |
ad_user_data |
marketing |
ad_personalization |
marketing |
functionality_storage |
preferences |
personalization_storage |
preferences |
security_storage |
always granted |
You can override this mapping in config.
OpenCookie is not a full consent management platform. It does not include a backend, hosted dashboard, user accounts, remote config, cookie scanner, vendor scanner, IAB TCF, audit logs, cross-device sync, or legal compliance guarantees.
Made by Guidelamego.