JS API

import {
  getConsent,
  getConsentRecord,
  setConsent,
  onConsentChange,
  whenAccepted,
  gateScript,
} from 'astro-cookie-consent';

getConsent(category?, options?)

getConsent(); // 'accept' | 'decline' | null — reads the 'all' category
getConsent('analytics'); // 'accept' | 'decline' | null for a specific category

Returns null if nothing is stored, or if the stored record has expired.

getConsentRecord(options?)

getConsentRecord(); // { categories: {...}, timestamp } | null

The raw stored record — every category’s current value plus when it was set. Returns null if expired or unset. Useful as an audit trail (GDPR Art. 7(1) accountability) — see GDPR-related features.

setConsent(value)

setConsent('accept'); // sets it programmatically and broadcasts the change
setConsent({ analytics: true, marketing: false }); // per-category form

onConsentChange(callback)

onConsentChange((record) => {
  // record.categories is the full map, e.g. { all: true }
  // or { analytics: true, marketing: false }
});

Fires on every future change, with the full record (not just a single category).

whenAccepted(callback, category?)

whenAccepted(() => {
  /* fires immediately if already accepted, or once accepted */
});
whenAccepted(() => {
  /* same, scoped to one category */
}, 'analytics');

Never calls back on decline.

gateScript(options)

gateScript({ src: '...', onLoad: () => {} }); // load a script only after consent
gateScript({ src: '...', category: 'analytics' }); // same, scoped to one category

Option	Type	Default	Description
src	string	—	Required. The script URL to load once accepted.
async	boolean	true	Sets script.async.
onLoad	function	—	Called once the script has loaded.
category	string	'all'	Which category must be accepted to inject it.

Never injects the script until the visitor accepts, and never injects it twice.

Conditionally showing content

gateScript covers loading a third-party script. For showing or hiding your own UI based on consent — a widget, a “manage cookies” link, an embed placeholder — combine getConsent() and onConsentChange() directly. This is exactly the pattern the “Analytics widget” on the homepage uses, reacting live as you toggle the banner:

<div id="analytics-widget">Waiting for consent…</div>

<script>
  import { getConsent, onConsentChange } from 'astro-cookie-consent';

  const widget = document.getElementById('analytics-widget');

  const render = (value: 'accept' | 'decline' | null) => {
    if (!widget) return;
    widget.textContent =
      value === 'accept'
        ? 'Analytics widget — visible'
        : value === 'decline'
          ? 'Hidden until you accept analytics'
          : 'Waiting for consent…';
  };

  render(getConsent('analytics')); // set the initial state on load
  onConsentChange(() => render(getConsent('analytics'))); // update on every change
</script>

getConsent() on load handles a returning visitor who already chose; onConsentChange() handles them changing their mind later via the reopen button — both are needed for the content to always match the current choice.

For a fuller version of this — a placeholder with an inline “Enable” button for a third-party embed — see Disabling individual widgets.

Expiry

A stored choice expires after expiryDays (default 365, configurable via the expiryDays prop on <ConsentBanner />, or the expiryDays option on getConsent/getConsentRecord) — after that, both return null again and the banner reappears on next load.