Design a cookie consent manager

Requirements exploration

Most people think a consent banner is a box with two buttons. The box is the easy part. The real product is a gate: a small piece of code that stands between the page and every analytics tag, ad pixel, and video embed, and only opens the gate for the purposes the visitor agreed to.

A few words first. A cookie is a small value the browser stores for a site and sends back with requests. Similar storage means anything else that keeps data on the device, such as localStorage, IndexedDB, or a tracking pixel that reads a stored id.

A consent management platform (CMP) is the product we are designing: the banner, the preferences screen, the stored choice, and the API other code asks. A purpose (or category) is a reason to store data, such as analytics or marketing.

Questions to ask first

• Where are the visitors? EU and UK visitors generally need to opt in before non-essential storage. Most US state laws are opt-out instead. If the site only serves one country, the design gets much simpler.
• Which third parties run today? List them: analytics, ad pixels, A/B testing, chat, video, maps. Each one must be put in a category and blocked until allowed. A store often has 10 to 30 of these tags.
• How are tags added? Hard-coded in the HTML, through a tag manager such as Google Tag Manager, or bundled in our JavaScript? Each path needs its own way of blocking.
• Build or buy? OneTrust, Cookiebot, Didomi, and others sell this. We design it either way, because even a bought CMP must be wired into our pages, tests, and SDKs.
• Do we serve ads through ad exchanges? If yes, ad partners usually expect the IAB Transparency and Consent Framework (TCF) signal. If no, a simple category model is enough.
• Do we need proof? Regulators can ask a company to show that consent was given. That means storing a record on the server, not only in the browser.
• How many languages and pages? The banner text must be translated and it shows on every page, so it is part of every page's performance budget.

Functional requirements

• Show a first-layer banner on the first visit with Accept all, Reject all, and Customize, with equal weight.
• A preferences screen (the second layer) with one toggle per category, a short description, and the list of vendors in each.
• Block every non-essential script, pixel, and iframe until its category is allowed, and run it right after it is allowed, without a reload.
• Replace blocked embeds (YouTube, maps) with a click-to-load placeholder.
• Store the choice with a version and a timestamp, send a consent receipt to the server, and ask again when the purposes change or the choice expires.
• Show the right banner for the visitor's region and honor the Global Privacy Control signal.
• A link in the footer that reopens the preferences at any time, so withdrawing is as easy as agreeing.
• A JavaScript API for our own code and SDKs: read the current consent and listen for changes. Send Google Consent Mode signals.

Non-functional requirements

Out of scope

• The analytics SDK itself and how it queues events under consent: see the analytics-sdk guide.
• How third-party loaders and widgets are built: see the embeddable-widget guide.
• Writing the privacy policy and deciding the legal basis for each purpose: that is the legal team's job. We build the tool that shows and enforces their decisions.
• Server-side tracking pipelines. They still need the consent signal, which our API provides.

What makes this hard

A consent manager has a small UI and a large blast radius. Five things drive every later decision.

1. It must act before anything else. A tag that runs 50 ms before the gate is ready has already sent a request and maybe set a cookie. You cannot take that back. So the gate must load first, and everything it guards must wait.
2. It does not own the code it blocks. Analytics, pixels, and embeds are written by other companies and added by other teams. The gate has to stop code it has never seen, added in ways it does not control.
3. It is judged by regulators, not only users. Button colors, the number of clicks to reject, and the wording are all things regulators have fined companies for. UX choices here are compliance choices.
4. The rules depend on where the visitor is. Opt-in in the EU and UK, opt-out in California, and different again elsewhere. The same page must behave differently by region, and the page is usually cached on a CDN.
5. It sits on every page, on the critical path. It loads early and shows on first visits, which are exactly the visits that Core Web Vitals and first impressions are measured on.

Notice the tension between the first and the last point. The gate must load before every tag, which pushes it to the very top of the page. But anything at the top of the page can slow down the first paint. Most of the performance chapter is about getting both.

What must wait for consent

Before we design the gate, we need to know what it guards. Here is the simplified picture an engineer needs. Again, this is not legal advice: the legal team decides, and we build a design that can follow whatever they decide.

The EU and the UK: opt in first

In the EU, the ePrivacy Directive (Article 5(3)) says that storing or reading information on a visitor's device needs their consent. The exception is storage that is strictly necessary for a service the visitor asked for. The rule covers cookies and similar storage: the EDPB (the board of EU data protection authorities) has said it also covers localStorage, tracking pixels, and some fingerprinting.

GDPR sets the bar for what counts as consent: freely given, specific, informed, and an unambiguous action. Silence, scrolling, or a pre-ticked box is not consent. The EU Court of Justice confirmed the pre-ticked box point for cookies in the Planet49 case in 2019.

The UK has the same model under PECR (the Privacy and Electronic Communications Regulations), enforced by the ICO. The Data (Use and Access) Act 2025, whose PECR changes took effect in early 2026, added a few narrow exceptions. One covers analytics used only to collect statistics that improve the site; another covers remembering how a visitor wants the site to look or work. Both apply only if visitors get clear information and a simple, free way to object.

Whether a given analytics setup fits that exception is a question for the legal team, and the ICO's guidance treats it narrowly. So design for it: a category can be switched from opt-in to opt-out per region by configuration, with the objection control in the preferences screen.

What counts as strictly necessary

The US: opt out, and honor GPC

Most US state privacy laws, led by California's CCPA as amended by the CPRA, are opt-out. Tags may run by default, but the visitor must be able to say no to the "sale" or "sharing" of their data, usually through a link named "Do Not Sell or Share My Personal Information". Sharing includes giving data to ad networks for cross-context behavioral ads, the legal term for ads based on activity across other sites.

California's regulations also require honoring the Global Privacy Control (GPC), a browser setting that tells every site "do not sell or share my data". The California Attorney General's 2022 settlement with Sephora was partly about ignoring it. Several other states now require similar opt-out signals, and the list keeps growing, so treat it as a per-region setting the legal team owns.

Blocking scripts until consent

This is the core of the design. The naive version is what many sites shipped first: load every tag as usual, show a banner, and if the visitor clicks Reject, delete the cookies.

Picture a product page with Google Analytics, a Meta pixel, and a YouTube video. Within 300 ms of the first byte, all three have contacted their servers, sent the page URL and IP address, and set cookies. The visitor reads the banner for 4 seconds and clicks Reject.

The gate deletes the _ga cookie it can see. The pixel's cookies on the vendor's domain are untouched, and the requests are already logged on three servers.

How inert tags work

The browser only runs a script whose type is empty, a JavaScript MIME type, or module. Any other type, such as text/plain, makes the element a data block: it stays in the DOM and does nothing. One detail trips people up: changing the type of a script that is already in the document does not run it. The browser only prepares a script at a few moments, mainly when it is inserted, and a change of type is not one of them.

So the gate creates a new element, copies the attributes, and inserts it. Two details matter in that copy. Under a Content Security Policy (CSP) with nonces, the browser hides the nonce attribute after the page loads, so getAttribute("nonce") returns an empty string: copy the nonce property instead. And a script inserted from JavaScript runs asynchronously by default, so an inline tag that needs its vendor's library must wait for that script's load event.

function activateScripts(allowed: Set<Category>) {
  const inert = document.querySelectorAll<HTMLScriptElement>(
    'script[type="text/plain"][data-category]'
  );
  for (const old of inert) {
    const cat = old.dataset.category as Category;
    if (!allowed.has(cat)) continue;
    const s = document.createElement("script");
    for (const { name, value } of old.attributes) {
      if (name !== "type" && name !== "nonce") s.setAttribute(name, value);
    }
    s.nonce = old.nonce; // the attribute reads as "" once hidden
    s.text = old.text; // inline tags keep their body
    old.replaceWith(s); // a new element, so the browser runs it
  }
}

<script type="text/plain" data-category="analytics"
  src="https://www.googletagmanager.com/gtag/js?id=G-XXXX" async></script>
<script type="text/plain" data-category="marketing">
  /* inline pixel snippet */
</script>
<div class="embed-placeholder" data-category="marketing"
  data-src="https://www.youtube.com/embed/abc123">
  <button>Load video (YouTube sets cookies)</button>
</div>

With the nonce copied, the new element passes the same CSP as the original. Read the third-party-scripts lesson for how CSP and third-party tags interact.

Iframes: click to load

An iframe has the same problem as a script: the moment its src is set, the browser contacts the vendor. So embeds are rendered as a placeholder with the video's thumbnail stored on our own server, a title, and a button. Clicking the button can either load just this one embed, or grant the whole category. Loading just this one is kinder: the visitor wanted one video, not every marketing tag.

YouTube's privacy-enhanced mode (youtube-nocookie.com) does not remove the need for the placeholder. Google describes it as keeping the view from personalizing YouTube and ads, not as storing nothing. Independent tests show the player still contacts Google when it loads and writes to localStorage, with cookies once the video plays. It is a good default after consent, not a replacement for it.

Categories, purposes, and vendors

Consent has to be specific: the visitor agrees to a purpose, not to "cookies" in general. The naive design has one switch, on or off. It fails the moment a visitor wants analytics but not ads: they click Reject all, and we lose the analytics we could have had.

The configuration is one JSON file owned by the privacy team: categories with their descriptions in every language, and vendors with their category, cookie names, lifetime, privacy policy link, and the config version that added them. The banner, the preferences screen, the gate, the CI test, and the cookie table in the privacy policy are all generated from it. One source means the policy page never disagrees with what the code blocks.

A short note on IAB TCF

The IAB Transparency and Consent Framework is an industry standard for ad tech. A TCF CMP must be registered with IAB Europe, expose a global __tcfapi function, and store the choice as a compact TC string that it passes to ad vendors.

Version 2.2 (2023) removed legitimate interest as a basis for ad and content personalization. Version 2.3, required for new TC strings since March 2026, makes the string always record which vendors were shown to the visitor. Treat TCF as an add-on in the interview: mention it when ads are in scope and move on.

The banner: fair by design

The banner is where many of the best-known fines came from. In January 2022 the French regulator CNIL fined Google 150 million euros and Facebook 60 million euros, mainly because accepting took one click and refusing took several. A year later the EDPB cookie banner taskforce published the banner practices most EU regulators agreed were not valid. The design rules below come from those two sources and the ICO's guidance.

• Reject on the first layer. If Accept all is on the first layer, Reject all must be there too, as a button, not a link hidden in the text.
• Equal prominence. Same size, same style, same contrast. A bright Accept next to a grey Reject is a nudge. Regulators assess this case by case, so equal is the safe default.
• No pre-ticked boxes. Every non-essential toggle in the preferences starts off.
• No cookie walls, in most cases. Blocking the whole site until the visitor accepts makes consent not freely given, according to the EDPB. A few countries allow a paid alternative in some cases; that is a legal decision, not ours.
• Clear words. Say what each category does in plain language. "We value your privacy" tells the visitor nothing.
• Withdrawal as easy as consent. A permanent way back to the choices, covered in the architecture chapter.

The design is layered. The first layer is short: one or two sentences, a link to the policy, and three equal buttons: Accept all, Reject all, Customize. The second layer is the preferences screen: one toggle per category, each with a description and an expandable vendor list. It has Save choices, Accept all, and Reject all at the bottom.

Try it yourself. The lab below lets you change the banner the way a growth team might ask you to, and shows which guidance each change runs into.

Storing the choice, regions, and GPC

Once the visitor chooses, we must remember it, so the banner does not come back on the next page, and we must be able to show later that consent was given. The naive version stores consent=yes in localStorage.

Three problems follow. The server cannot read localStorage, so server-rendered pages cannot know whether to include tags or the banner. There is no version, so when marketing adds a new ad vendor next month, old consents silently cover it. And there is no proof on our side if a regulator asks.

type Category = "preferences" | "analytics" | "marketing";

type ConsentRecord = {
  v: number;        // config version the visitor saw, such as 7
  id: string;       // random receipt id, not a user id
  ts: number;       // when they chose, epoch seconds
  region: "eu" | "uk" | "us-opt-out" | "other";
  granted: Category[];  // empty after Reject all
  src: "banner" | "preferences" | "gpc";
};
// Cookie value, URL-encoded JSON, about 120 bytes:
// {"v":7,"id":"k3f9","ts":1792572000,"region":"eu","granted":["analytics"],"src":"banner"}

Consent receipts

GDPR expects a company to be able to show that a person consented. So every choice also creates a consent receipt on the server: the receipt id, the config version and its text in that language, the categories granted, the timestamp, the region, and the source. No name or email is needed: the random id in the cookie links the browser to its receipt. The banner sends it with fetch and keepalive: true, so the request finishes even if the visitor clicks a link right away.

Note the order in the flow. The gate applies the choice in the browser first, then sends the receipt. If the receipt fails, the visitor's choice still holds for this page.

The banner writes a short-lived fallback cookie from JavaScript and retries the receipt on the next page view. We never block the visitor on our own server being up.

When to ask again

• The config version changes in a way that matters. A new vendor in an already granted category, or a new purpose, bumps v. If the stored v is older, the banner shows again. Until the visitor answers, the gate allows only vendors whose added-in version is at or below the stored v, so the old answer covers exactly what it listed. Fixing a typo does not bump it.
• The choice gets old. CNIL considers about 6 months a generally appropriate time to keep a choice, accept or reject, before asking again. Many CMPs use 6 to 12 months. We make it a per-region setting, with 6 months for the EU, and use it as the cookie's Max-Age: when the cookie expires, the visitor is back to unknown.
• The cookie is missing. Cleared cookies, a new browser, or private browsing mean a fresh start. That is expected.

Regional rules

Our visitors come from the EU, the UK, the US, and elsewhere, and each region needs a different default and a different first layer. The page needs to know the region before it decides what to block, which means before any non-essential tag could run.

Why put the rule set in the HTML and not read the consent cookie on the server to decide everything? Because the HTML must stay cacheable. If the server rendered different HTML per consent value, the CDN would need a variant for every combination of cookie values.

Instead, the HTML always contains the tags in their inert form plus a 1 KB inline bootstrap. The bootstrap reads the cookie in the browser and activates what is allowed. It is the same trick the dark-mode-theming guide uses to apply the theme before first paint.

Global Privacy Control

The analytics-sdk guide explains how the GPC signal reaches a page (the Sec-GPC: 1 request header and navigator.globalPrivacyControl) and which browsers send it. For the CMP, the question is where to apply it: in the bootstrap, before any tag runs, as a per-region rule. In California and the states with similar rules it is a required opt-out of sale and sharing. In the EU nothing runs without opt-in anyway, and many sites also treat it as a no to marketing.

const gpc = navigator.globalPrivacyControl === true;
const rules = window.__CC_RULES__; // written by the edge: "eu", "uk", "us-opt-out", "other"
const stored = readConsentCookie(); // null on a first visit

let granted: Category[];
if (stored) granted = stored.granted; // an expired cookie is already gone
else if (rules === "us-opt-out") granted = ["preferences", "analytics", "marketing"];
else granted = []; // opt-in regions and unknown: nothing until asked

// A per-region setting from the config; required for "us-opt-out".
if (gpc && config.gpcBlocksMarketing[rules]) granted = granted.filter((c) => c !== "marketing");
// Show a note in the preferences: "Your browser's privacy signal was applied"

The last line matters. When GPC overrides a stored Accept, tell the visitor in the preferences screen, so they understand why ads look different. If they later turn Marketing on themselves, record it with src: "preferences"; how much weight that later choice has against GPC is a question for the legal team.

Architecture and the consent API

Now we can put the pieces together. The key split is between what must run first and what can wait. The bootstrap is tiny and inline: it reads the cookie, applies the region rules and GPC, sets Consent Mode defaults, and activates already-allowed tags.

The banner UI is only needed on a first visit or when the visitor opens the preferences, so it loads later and only when needed. Returning visitors, who are most visitors, never download the UI.

Why is the store inside the bootstrap and not in the UI bundle? Because our own app code and SDKs ask "may I track?" on every page, including pages where the banner never loads. Why is the UI not inline? Because inlining 10 KB of UI and text into every HTML response would slow every page, and most page views come from visitors who already chose.

If the CMP were a product that other companies install, like OneTrust, this bootstrap would become a one-tag loader on pages we do not own. The embeddable-widget guide covers that case: a small loader, isolating our CSS and JavaScript, and working under the host's CSP.

Data model

The last row is worth saying out loud in an interview. Toggles in the preferences screen are a draft. Flipping a toggle must not change the store, because a visitor who flips Marketing on and then closes the dialog has not consented. Only Save, Accept all, or Reject all commit.

The consent API

Inert tags cover scripts in the HTML. But our own code also needs to ask: the analytics SDK bundled in the app, the A/B testing client, the recommendations widget that remembers recent views. They need a small, stable API on window, ready before any of them run.

interface ConsentApi {
  /** Current state; never waits. "unknown" means not answered yet. */
  get(): { status: "unknown" | "answered"; granted: Category[]; gpc: boolean };
  has(category: Category): boolean;
  /** Called now with the current state, then on every change. Returns unsubscribe. */
  onChange(cb: (granted: Category[]) => void): () => void;
  /** Run once, as soon as the category is granted (now, or later). */
  whenGranted(category: Category, run: () => void): void;
  openPreferences(): void; // loads the UI on demand
  version: number;
}
declare global { interface Window { consent: ConsentApi } }

// In the app:
window.consent.whenGranted("analytics", () => import("./analytics").then((m) => m.init()));

Two design points. onChange calls back right away with the current state, so a subscriber that attaches late cannot miss the answer that came before it. And whenGranted pairs well with dynamic import(): the analytics bundle is not even downloaded until it may run. The analytics-sdk guide shows how an SDK can queue events while consent is unknown and drop or send them once it is answered.

Google Consent Mode v2

Google tags read their own consent signals. Version 2, which Google has required since March 2024 for ads measurement and personalization with visitors in the EEA, has four main ones: ad_storage, analytics_storage, ad_user_data, and ad_personalization. The bootstrap sets defaults before any Google tag, and the store sends an update on every change.

gtag("consent", "default", {
  ad_storage: "denied", ad_user_data: "denied",
  ad_personalization: "denied", analytics_storage: "denied",
  wait_for_update: 500, // ms the tags wait for an update
});

consent.onChange((granted) => {
  const m = granted.includes("marketing") ? "granted" : "denied";
  const a = granted.includes("analytics") ? "granted" : "denied";
  gtag("consent", "update", {
    ad_storage: m, ad_user_data: m, ad_personalization: m, analytics_storage: a,
  });
});

The analytics-sdk guide compares Consent Mode's basic setup, where Google tags do not load until consent, with its advanced setup, where they load and send cookieless pings while denied. Our gate keeps the Google tag inert until a category is granted, which is the basic setup. The defaults still matter: when a visitor grants analytics but not marketing, the Google tag loads and must already know the ad signals are denied. Advanced mode stays behind a per-region config switch for the legal team.

Reopening and withdrawing

GDPR says withdrawing must be as easy as giving consent. So every page has a Cookie settings link in the footer that calls consent.openPreferences(). The taskforce report mentions a small floating icon or a link in a visible place as ways to do this; a footer link on every page is the common choice.

Withdrawing is harder than granting, because code that already ran cannot be un-run. When a category is turned off, the store saves the new record and sends a receipt. It notifies subscribers, so SDKs stop sending and Consent Mode gets denied. It deletes the first-party cookies listed for that category's vendors, such as _ga and _ga_XXXX, using the same Domain and Path they were set with, or the delete silently misses.

Then the preferences screen offers a reload, because a script already running in the page, like a pixel listening to clicks, cannot be fully stopped otherwise. Cookies on the vendor's own domain stay; the policy should tell visitors how to clear them.

Performance, accessibility, and testing

Performance: on every first visit

First visits are when the banner shows, and first visits are also the slowest, with cold caches. Four mistakes are common, and each hurts a Core Web Vital (see the core-web-vitals lesson).

• The banner pushes the page down (CLS). A banner inserted at the top of the normal flow after the first paint moves every element below it. On a phone that can add a layout shift score of 0.1 or more by itself, the edge of the good range. Fix: position: fixed at the bottom, so it overlays content and moves nothing.
• The banner becomes the LCP element. LCP picks the largest text or image block in the viewport. On a 375 px wide phone, a banner with four lines of text can be bigger than the page's headline, and because it appears late, after the CMP script, it makes LCP late. Fix: keep the first-layer text short so the headline or hero image stays the largest element, have the bootstrap start loading the banner UI as soon as it knows the banner is needed, and test LCP on a phone viewport with the banner showing.
• The CMP script blocks rendering. A synchronous external CMP script in head holds up first paint until it downloads. Fix: the inline 1 KB bootstrap decides, and the UI loads with async or a dynamic import() only when needed.
• Accept all makes INP slow. INP (Interaction to Next Paint) measures how long the page takes to paint after a click. If the Accept handler inserts every tag in one task, the banner stays on screen while they all parse and run. Fix: hide the banner and commit the choice first, then yield to the browser (for example with setTimeout) before the gate activates the tags.

Blocking also helps performance. On a typical store, the tags behind the gate add hundreds of KB of JavaScript. Visitors who reject get a much lighter page. Measure both groups separately in real user monitoring, or the averages will hide it.

Accessibility

• First layer: a labelled region, not a modal. Use a section with aria-labelledby pointing to its heading, or a non-modal dialog opened with show(). The visitor can keep reading with a screen reader, and nothing traps focus.
• Do not steal focus on load. Moving focus into the banner on page load interrupts screen reader users mid-page. Instead, place the banner early in the DOM order, right after the skip link, so it is reached with a few Tab presses.
• Second layer: a real modal. The preferences screen is a task, so open it with showModal(): focus moves in, the page behind is inert, Escape closes it, and focus returns to the button or footer link that opened it. The focus-management lesson covers the return focus.
• Do not hide the focused element. A fixed banner can cover the link or field a keyboard user just tabbed to, which fails WCAG 2.2's Focus Not Obscured rule. Set scroll-padding-bottom on the page to the banner's height, so the browser scrolls focused elements above it.
• Toggles are switches. A button with role="switch" and aria-checked, or a checkbox, with a visible label and the description linked by aria-describedby. Necessary shows as on and disabled, with a text reason.
• Readable. Text contrast of at least 4.5 to 1, buttons at least 24 by 24 CSS pixels (WCAG 2.2), and a layout that still works at 200 percent zoom without the banner covering the whole screen.

Testing: prove nothing leaks

The most valuable test is simple: load key pages in a headless browser with no consent cookie, record every network request, and fail the build if any request goes to a host that is not on the allow list for necessary. Then click Reject all and check again, and click Accept all and check that the expected vendors do load. Run it for each rule set by faking the region.

import { test, expect } from "@playwright/test";
import { necessaryHosts, necessaryCookies } from "../consent.config";

for (const path of ["/", "/product/123", "/blog/launch"]) {
  test(`no tracking before consent on ${path}`, async ({ page }) => {
    const hosts = new Set<string>();
    page.on("request", (r) => hosts.add(new URL(r.url()).host));
    await page.goto(path, { waitUntil: "networkidle" });
    await page.waitForTimeout(2000); // late tags
    const leaks = [...hosts].filter((h) => !necessaryHosts.includes(h));
    expect(leaks).toEqual([]);
    const names = (await page.context().cookies()).map((c) => c.name);
    expect(names.filter((n) => !necessaryCookies.includes(n))).toEqual([]);
  });
}

Also run the check against production on a schedule, because marketing adds tags in the tag manager without a deploy. And add axe checks for the banner and the preferences in both states (see the e2e-tests lesson).

Running it in the interview

This question is often asked as an easy one, and candidates lose it by spending 25 minutes on the banner's look. The interviewer wants to see that you know the banner is the small part and the gate is the real system.

Draw the gate first, not the banner: an HTML page with three inert tags, the bootstrap above them, and an arrow from the store to the gate. Everything else hangs off that picture. Say out loud that the legal rules come from the privacy team and that your design makes each rule a setting, such as opt-in or opt-out per region and the re-ask interval. That shows you know where engineering ends.

Follow-up questions to expect