@ngrithms/cookie-consent

Modern Angular cookie consent — standalone components, signal-based state, provideCookieConsent() functional setup, SSR-safe, zero runtime dependencies.

Built as a from-scratch replacement for the abandoned NgModule-era consent libraries. Designed for Angular 17 and up.

Project home: ngrithms.aalbadra.workers.dev/cookie-consent · part of the @ngrithms family of modern Angular utilities.

Features

• ✅ Standalone components, no NgModule, no forRoot()
• ✅ Signal-based reactive consent state (with RxJS observable bridges)
• ✅ Two-level data model: Category (visual group) → CookieItem (toggle) → CookieDetail (informational)
• ✅ *ngrIfConsent="'item-key'" structural directive
• ✅ Preset category constants (ANALYTICS_PRESET, MARKETING_PRESET, ...) — spread them in or use as templates
• ✅ First-class Google Consent Mode v2 adapter
• ✅ Built-in i18n (en, fr) + custom-language API with icon path + fallback
• ✅ Fully customizable copy via translation keys — no markup forks needed
• ✅ Optional CSS theme presets — or go headless and style it yourself
• ✅ SSR-safe out of the box
• ✅ Zero runtime dependencies

Install

npm install @ngrithms/cookie-consent

Quick start

Three files — matches what ng new scaffolds.

// src/app/app.config.ts — register the provider
import { ApplicationConfig } from '@angular/core';
import { provideCookieConsent, ANALYTICS_PRESET, MARKETING_PRESET } from '@ngrithms/cookie-consent';

export const appConfig: ApplicationConfig = {
  providers: [
    provideCookieConsent({
      privacyPolicyUrl: '/privacy',
      defaultLanguage: 'en',
      categories: [ANALYTICS_PRESET, MARKETING_PRESET],
    }),
  ],
};

// src/app/app.component.ts — import the standalone components & directive
import { Component } from '@angular/core';
import { ConsentBannerComponent, ConsentBadgeComponent, IfConsentDirective } from '@ngrithms/cookie-consent';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [ConsentBannerComponent, ConsentBadgeComponent, IfConsentDirective],
  templateUrl: './app.component.html',
})
export class AppComponent {}

<!-- src/app/app.component.html -->
<ngr-consent-banner></ngr-consent-banner>
<ngr-consent-badge></ngr-consent-badge>

<div *ngrIfConsent="'google_analytics'">
  <!-- Only rendered if the user consented to Google Analytics. -->
</div>

/* src/styles.css — pick a theme, or skip this and theme it yourself */
@import '@ngrithms/cookie-consent/themes/default.css';

Prefer the inline bootstrapApplication(App, { providers: [...] }) style? It works too — just put provideCookieConsent(...) in that providers array instead of in app.config.ts. Both produce identical results; the app.config.ts split above matches the default Angular scaffold.

Building custom categories

The preset above is the fastest path. Most real apps end up wanting some items from a preset and not others — so v0.6 made every cookie item a first-class export, and added a makeCategory(...) helper for hand-assembled categories:

import {
  provideCookieConsent, makeCategory,
  GOOGLE_ANALYTICS, GOOGLE_ADS, META_PIXEL, YOUTUBE,
} from '@ngrithms/cookie-consent';

provideCookieConsent({
  categories: [
    makeCategory({
      key: 'analytics',
      name: { en: 'Analytics' },
      items: [GOOGLE_ANALYTICS],     // just GA, not the whole preset
    }),
    makeCategory({
      key: 'tracking',
      name: { en: 'Tracking & Ads' },
      items: [GOOGLE_ADS, META_PIXEL],  // group them how YOU think about them
    }),
    makeCategory({
      key: 'embeds',
      name: { en: 'Third-party embeds' },
      items: [YOUTUBE],
    }),
  ],
});

See the library README for the full list of available items and detailed patterns.

Documentation

Full API reference, configuration options, recipes (Google Consent Mode v2, custom themes, headless mode, SSR, schema migration), and details on ScriptLoaderService / *ngrIfConsent / the reactive ConsentService API live in the published library README:

• Library README — the canonical API surface (also shipped to npm)
• Demo app — runnable showcase: npm run start:demo
• Changelog

Repository layout

projects/
  cookie-consent/   # the published library (@ngrithms/cookie-consent)
  demo/             # consumer app used as a live showcase

Development

npm install
npm test                # vitest, 117 unit specs, ~3s
npm run build:lib       # ng build cookie-consent → dist/cookie-consent
npm run start:demo      # ng serve demo

npm test runs the library suite (vitest under jsdom via @angular/build:unit-test). CI also runs npm test on every push and pull request.

Releasing

1. Update CHANGELOG.md — move [Unreleased] to the new version + date.
2. npm run release:patch | release:minor | release:major — bumps projects/cookie-consent/package.json and the workspace package.json. No git tag or publish is created.
3. npm run build:lib
4. cd dist/cookie-consent && npm publish --access public
5. Commit, tag vX.Y.Z, push branch + tag.

License

MIT © Aboud Badra