Skip to content
codus/consent

Cookie & Storage

Default behavior

Section titled “Default behavior”

By default, the library stores consent in a cookie named cc_cookie with these settings:

{
  name: "cc_cookie",
  expiresAfterDays: 182,    // ~6 months
  domain: "",               // Auto: location.hostname
  path: "/",
  secure: true,
  sameSite: "Lax",
}
Section titled “Customizing the cookie”

All cookie settings are configured through the cookieStorage() factory:

import { createConsent, cookieStorage } from "@uabcodus/consent/core";


const consent = createConsent({
  storage: cookieStorage({
    name: "my-consent-cookie",
    expiresAfterDays: 365,
    domain: ".example.com", // Share across subdomains
    path: "/",
    secure: true,
    sameSite: "Strict"
  }),
  categories: {
    necessary: { readOnly: true },
    analytics: {}
  } as const
});

Dynamic expiration

Section titled “Dynamic expiration”

expiresAfterDays can be a function. For example, set longer expiration when the user accepts all categories:

storage: cookieStorage({
  expiresAfterDays: (acceptType) => {
    if (acceptType === "all") return 365;
    if (acceptType === "necessary") return 90;
    return 182;
  },
}),

Using localStorage

Section titled “Using localStorage”

Switch from cookies to localStorage by providing the localStorageStorage() adapter:

import { createConsent, localStorageStorage } from "@uabcodus/consent/core";


const consent = createConsent({
  storage: localStorageStorage("cc_cookie"),
  categories: {
    necessary: { readOnly: true },
    analytics: {}
  } as const
});

The first argument is the localStorage key name. Optionally pass an expiry in milliseconds as the second argument (defaults to 182 days).

Custom storage adapters

Section titled “Custom storage adapters”

The StorageAdapter interface lets you plug in any persistence mechanism:

interface StorageAdapter {
  get(): CookieValue;
  set(value: CookieValue): void;
  remove(): void;
}

For example, you could implement sessionStorage, IndexedDB, or a server-side backend.

When using localStorage, the library also stores an expirationTime and checks it on page load. Expired consent is treated as invalid, same as with cookies.

Section titled “Reading cookie data”

Use getCookie() or getCookie(field) to read consent data:

const cookie = consent.getCookie();
// { categories: [...], services: {...}, consentId: "...", ... }


const consentId = consent.getCookie("consentId");
// "a1b2c3d4-..."


const timestamp = consent.getCookie("consentTimestamp");
// "2025-01-01T00:00:00.000Z"

Storing custom data

Section titled “Storing custom data”

Need to store additional data alongside consent? Use setCookieData():

// Replace the entire data field
consent.setCookieData({ value: { userId: "123" }, mode: "set" });


// Merge into existing data (shallow merge for objects)
consent.setCookieData({ value: { theme: "dark" }, mode: "update" });

The data is accessible later:

const data = consent.getCookie("data");
// { userId: "123", theme: "dark" }

Returns true if anything actually changed (so you can avoid unnecessary writes).

Erasing cookies

Section titled “Erasing cookies”

Manually erase cookies by name, RegExp, or array of both:

// Single cookie
consent.eraseCookies("_ga");


// Regex — erase all GA cookies
consent.eraseCookies(/^_ga/);


// Array
consent.eraseCookies(["_ga", "_gid", /^_gat/]);


// Custom path and domain
consent.eraseCookies("_ga", "/subdir", ".example.com");

This is handled automatically for rejected categories when autoClearCookies is enabled (default: true). But you can call it manually too — useful for cleaning up cookies from a previous consent plugin.

Subdomain cookies

Section titled “Subdomain cookies”

To share consent across subdomains, set the domain to the root domain with a leading dot:

storage: cookieStorage({
  domain: ".example.com"
});

This makes the cookie available on www.example.com, app.example.com, blog.example.com, etc.

For localhost development, leave domain empty (default) — most browsers ignore domain on localhost.

Next steps

Section titled “Next steps”