The Cookie Store API

The problem with document.cookie

document.cookie is a synchronous API designed in the mid-1990s. It has three well-known friction points:

Parsing is manual — reading a specific cookie requires splitting and looping.
Writes are string-based — you build a cookie string by hand.
No change events — there is no way to observe when another tab or the server changes a cookie.

The Cookie Store API solves all three with a clean, Promise-based interface.

Browser support

The Cookie Store API ships in Chrome and Edge (Chromium-based browsers). Firefox does not support it yet. Always feature-detect before using it.

Returns a Promise that resolves to a CookieListItem object or null if the cookie does not exist:

const cookie = await cookieStore.get('theme');
if (cookie) {
  console.log(cookie.name);    // 'theme'
  console.log(cookie.value);   // 'dark'
}

The returned object also includes domain, path, expires, secure, sameSite, and httpOnly properties.

Accepts a name/value string pair or an options object:

// Simple form
await cookieStore.set('theme', 'dark');

// Options form — recommended for control over attributes
await cookieStore.set({
  name: 'theme',
  value: 'dark',
  maxAge: 86400,
  sameSite: 'lax',
});

Returns a Promise that resolves when the cookie is written.

await cookieStore.delete('theme');

Returns a Promise that resolves when the cookie is deleted. This is equivalent to setting Max-Age=0.

cookieStore.getAll — read all cookies

const allCookies = await cookieStore.getAll();
allCookies.forEach(c => console.log(c.name, c.value));

Unlike document.cookie, this returns a proper array of objects — no string parsing required.

Change events

The Cookie Store API allows you to listen for cookie changes reactively:

cookieStore.addEventListener('change', event => {
  event.changed.forEach(c => {
    console.log('Cookie changed:', c.name, '=', c.value);
  });
  event.deleted.forEach(c => {
    console.log('Cookie deleted:', c.name);
  });
});

event.changed is an array of cookies that were set or updated. event.deleted is an array of cookies that were removed. This works across tabs for cookies that are not scoped to a single tab.

Feature-detect pattern

Because browser support is incomplete, always feature-detect and fall back to document.cookie:

async function getTheme() {
  if ('cookieStore' in window) {
    const c = await cookieStore.get('theme');
    return c ? c.value : null;
  } else {
    // document.cookie fallback
    var pairs = document.cookie.split('; ');
    for (var i = 0; i < pairs.length; i++) {
      var p = pairs[i].split('=');
      if (p[0] === 'theme') return decodeURIComponent(p[1]);
    }
    return null;
  }
}

Runnable demo: cookieStore with fallback

Browser Storage

async function run() {
  if ('cookieStore' in window) {
    // Modern async API
    await cookieStore.set({ name: 'demo_modern', value: 'hello', maxAge: 60 });
    var c = await cookieStore.get('demo_modern');
    console.log('cookieStore.get:', c ? c.value : null);
    await cookieStore.delete('demo_modern');
    var after = await cookieStore.get('demo_modern');
    console.log('After delete:', after ? after.value : null);
    console.log('Browser supports cookieStore API');
  } else {
    // Fallback to document.cookie
    document.cookie = 'demo_modern=hello; Max-Age=60; SameSite=Lax';
    var pairs = document.cookie.split('; ');
    var val = null;
    for (var i = 0; i < pairs.length; i++) {
      var p = pairs[i].split('=');
      if (p[0] === 'demo_modern') val = decodeURIComponent(p[1]);
    }
    console.log('document.cookie fallback:', val);
    document.cookie = 'demo_modern=; Max-Age=0; SameSite=Lax';
    console.log('Cookie Store API not available in this browser - used fallback');
  }
}
run();