astro-consent is a privacy-first cookie consent integration for Astro. It adds a polished consent banner or overlay, generates an editable stylesheet in your project, and exposes a tiny runtime API for managing stored consent.

• A banner or overlay consent UI
• A generated src/cookiebanner/styles.css file you can edit directly
• Idle-based display with a configurable fade-in delay
• Focus trapping, Escape to close, and focus return for the overlay
• CLI setup, removal, and diagnostics commands
• TypeScript support
• Compatibility with Astro 4, 5, and 6

npm install astro-consent

Use the CLI to wire everything into your Astro project:

npx astro-consent init

That will:

• add astro-consent to astro.config.*
• create src/cookiebanner/styles.css if it is missing
• add a starter configuration block with placeholder values

Open src/cookiebanner/styles.css in your project and customize the banner or modal visually. The package does not inject CSS through JavaScript, so this file is the single source of truth for styling.

npm run dev

The default install is designed to be easy to understand and safe to customise. A typical configuration looks like this:

import astroConsent from "astro-consent";

export default {
  integrations: [
    astroConsent({
      siteName: "My Website",
      headline: "Manage cookie preferences for My Website",
      description:
        "We use cookies to improve site performance, measure traffic, and support marketing.",
      acceptLabel: "Accept all",
      rejectLabel: "Reject all",
      manageLabel: "Manage preferences",
      cookiePolicyUrl: "/cookie-policy",
      privacyPolicyUrl: "/privacy",
      displayUntilIdle: true,
      displayIdleDelayMs: 1000,
      presentation: "banner",
      consent: {
        days: 30,
        storageKey: "astro-consent"
      }
    })
  ]
};

npx astro-consent init

Adds the integration import and a marked configuration block to astro.config.*, then creates src/cookiebanner/styles.css if the file does not already exist.

npx astro-consent remove

Removes the marked astro-consent block from astro.config.*, removes the import, and deletes src/cookiebanner/styles.css if it exists.

npx astro-consent doctor

Checks the following:

• Astro config import wiring
• astroConsent(...) integration wiring
• src/cookiebanner/styles.css existence
• src/layouts/BaseLayout.astro importing the stylesheet

Use JSON output for automation:

npx astro-consent doctor --json

npx astro-consent status

Reports the current install state:

• whether the Astro config is wired
• whether the stylesheet exists
• whether the package is linked into node_modules
• which consent storage key is configured
• a note explaining that actual consent state is browser-side

JSON output is also available:

npx astro-consent status --json

Preview changes without writing files:

npx astro-consent init --dry-run
npx astro-consent remove --dry-run

You can choose how the consent UI appears:

• banner for a standard bottom-of-page consent banner
• overlay for a centered modal-first experience

Example:

astroConsent({
  presentation: "overlay"
});

The consent UI can wait until the browser is idle before appearing, then fade in after a short pause.

When true, the banner or overlay waits for browser idle before showing.

Adds a delay after idle before the UI becomes visible.

Example:

astroConsent({
  displayUntilIdle: true,
  displayIdleDelayMs: 1000
});

These options let you tune the wording without editing the runtime:

• siteName sets the site name used in fallback copy
• headline sets the banner or dialog title
• description sets the explanatory text
• acceptLabel sets the primary action
• rejectLabel sets the reject action
• manageLabel sets the preferences action

Example:

astroConsent({
  siteName: "Escape Zone",
  headline: "Manage cookie preferences for Escape Zone",
  description:
    "We use cookies to improve site performance, measure traffic, and support marketing.",
  acceptLabel: "Accept all",
  rejectLabel: "Reject all",
  manageLabel: "Manage preferences"
});

The consent UI supports separate links for cookie and privacy policy pages.

• cookiePolicyUrl controls the cookie policy link
• privacyPolicyUrl controls the privacy policy link

If you still pass policyUrl, it will be used for both links as a backwards-compatible fallback.

The integration exposes a small browser API on window.astroConsent:

window.astroConsent.get();
window.astroConsent.set({ essential: true, analytics: true, marketing: false });
window.astroConsent.reset();

• get() returns the stored consent object if one exists and is still valid
• set(...) stores a new consent state
• reset() clears consent and reloads the page

The generated src/cookiebanner/styles.css file is meant to be edited directly.

It uses cb-* custom properties so you can change the visual style without rewriting selectors. The most useful tokens are:

• --cb-bg
• --cb-text
• --cb-muted
• --cb-border
• --cb-accent
• --cb-accent-strong
• --cb-success
• --cb-shadow
• --cb-banner-radius
• --cb-modal-width
• --cb-button-bg
• --cb-button-secondary-bg

The installer creates the stylesheet here:

src/cookiebanner/styles.css

That file is intentionally local to your project. It is not injected from the package at runtime, which keeps styling under your control and avoids overwriting custom work.

• Consent is stored in localStorage
• The stored value expires after the configured TTL
• Optional categories default to checked in the UI, but users can still reject them
• The overlay uses accessible dialog behavior, including focus trapping, Escape to close, and focus return to the trigger

Check the following:

1. npx astro-consent init has been run in the Astro project root
2. astro.config.* includes the astro-consent integration
3. src/layouts/BaseLayout.astro imports ../cookiebanner/styles.css
4. You have not already stored consent in localStorage

Run:

npx astro-consent init

Run:

npx astro-consent doctor

and follow the fix instructions it prints.

The design is intentionally simple:

• the runtime handles consent logic and UI behavior
• the generated stylesheet handles appearance
• the CLI wires setup and removal cleanly

That separation keeps the plugin predictable, easier to debug, and safer to customise.