npm Package

The truConsent npm package (@truconsent/consent-notice) provides the essential React components for implementing consent banners and user rights portals. It communicates with the truConsent API and handles rendering, state management, and submission for you.

Installation

npm install @truconsent/consent-notice

yarn add @truconsent/consent-notice

pnpm add @truconsent/consent-notice

Core API URLs

Depending on your use case, you will interact with one of two base URLs:

Environment	Base URL	Purpose
SDK / NPM	`https://api.truconsent.io`	Used by the `TruConsentModal` and `RightCenter` components
Admin / REST	`https://api.truconsent.io`	Used for server-side management and discovery

Environment configuration

We recommend using environment variables (e.g., in a .env file) to manage your API keys and configuration IDs securely.

VITE_TRUCONSENT_API_URL=https://api.truconsent.io
VITE_TRUCONSENT_API_KEY=your-consent-api-key
VITE_TRUCONSENT_ORG_ID=your-organization-id
VITE_TRUCONSENT_ASSET_ID=your-asset-id

Never commit your .env file to version control. Add it to .gitignore and use your deployment platform’s secrets management for production values.

1. Discovery: external API workflow

Before rendering components, you need two pieces of data from the truConsent API: your tenant’s assets and the collection point configuration. Both calls are authenticated with your API key and organization ID.

Step 1: Fetch assets

Call the public assets endpoint to retrieve your organization’s branding and configuration metadata.

const response = await fetch(
  'https://api.truconsent.io/api/v1/public/assets',
  {
    headers: {
      'X-API-Key': import.meta.env.VITE_TRUCONSENT_API_KEY,
      'X-Org-Id': import.meta.env.VITE_TRUCONSENT_ORG_ID,
    },
  }
);

const assets = await response.json();

A successful response returns your organization’s asset manifest:

{
  "asset_id": "a_abc123",
  "logo_url": "https://cdn.truconsent.io/assets/your-logo.png",
  "primary_color": "#a6ff00"
}

Step 2: Fetch collection points

Fetch the collection point configuration to get the purposes your consent banner needs to display. Pass asset_id as a query parameter to filter by asset.

const response = await fetch(
  `https://api.truconsent.io/api/v1/public/collection-points?asset_id=${import.meta.env.VITE_TRUCONSENT_ASSET_ID}`,
  {
    headers: {
      'X-API-Key': import.meta.env.VITE_TRUCONSENT_API_KEY,
      'X-Org-Id': import.meta.env.VITE_TRUCONSENT_ORG_ID,
    },
  }
);

const collectionPoints = await response.json();

Response:

[
  {
    "id": "CP001",
    "display_id": "signup-form",
    "name": "Sign-up Form",
    "consent_type": "explicit",
    "purposes": [
      {
        "id": "p_001",
        "name": "Marketing emails",
        "description": "Receive product updates and offers.",
        "is_mandatory": false
      },
      {
        "id": "p_002",
        "name": "Analytics",
        "description": "Help us improve the product.",
        "is_mandatory": false
      }
    ]
  }
]

The TruConsentModal component renders a fully configured consent banner. It manages the consent UI, user interactions, and submits decisions back to the truConsent API.

CSS import

Import the component stylesheet once at your app’s entry point.

import '@truconsent/consent-notice/tailwind.css';

import { TruConsentModal } from '@truconsent/consent-notice';
import '@truconsent/consent-notice/tailwind.css';

interface ConsentBannerProps {
  userId: string;
  logoUrl: string;
}

export function ConsentBanner({ userId, logoUrl }: ConsentBannerProps) {
  return (
    <TruConsentModal
      userId={userId}
      apiKey={import.meta.env.VITE_TRUCONSENT_API_KEY}
      organizationId={import.meta.env.VITE_TRUCONSENT_ORG_ID}
      bannerId="CP001"
      logoUrl={logoUrl}
      onClose={(type) => {
        // type is 'approved' | 'declined' | 'partial_consent'
        console.log('Consent submitted:', type);
      }}
    />
  );
}

'use client';

import { TruConsentModal } from '@truconsent/consent-notice';
import '@truconsent/consent-notice/tailwind.css';

export function ConsentBanner({ userId }: { userId: string }) {
  return (
    <TruConsentModal
      userId={userId}
      apiKey={process.env.NEXT_PUBLIC_TRUCONSENT_API_KEY!}
      organizationId={process.env.NEXT_PUBLIC_TRUCONSENT_ORG_ID!}
      bannerId="CP001"
      logoUrl="/logo.png"
      onClose={(type) => {
        // type is 'approved' | 'declined' | 'partial_consent'
        console.log('Consent decision:', type);
      }}
    />
  );
}

`TruConsentModal` props

Prop	Type	Required	Description
`userId`	`string`	Yes	Unique identifier for the user
`apiKey`	`string`	Yes	Your truConsent API key (consent scope)
`organizationId`	`string`	Yes	Your organization’s unique identifier
`bannerId`	`string`	Yes	The collection point ID (e.g., `"CP001"`)
`logoUrl`	`string`	Yes	URL to your organization’s logo image
`onClose`	`(type: string) => void`	Yes	Called when the user submits a decision. Receives `'approved'`, `'declined'`, or `'partial_consent'`

3. Rights centre integration

The RightCenter component provides a self-service portal where users can view their consent history, withdraw consent, and submit data rights requests.

CSS import

import '@truconsent/consent-notice/RightCenter.css';

Component implementation

React
Next.js App Router

import { RightCenter } from '@truconsent/consent-notice';
import '@truconsent/consent-notice/RightCenter.css';

interface RightsCentreProps {
  userId: string;
}

export function RightsCentre({ userId }: RightsCentreProps) {
  return (
    <RightCenter
      userId={userId}
      apiKey={import.meta.env.VITE_TRUCONSENT_ADMIN_API_KEY}
      organizationId={import.meta.env.VITE_TRUCONSENT_ORG_ID}
    />
  );
}

'use client';

import { RightCenter } from '@truconsent/consent-notice';
import '@truconsent/consent-notice/RightCenter.css';

export function RightsCentre({ userId }: { userId: string }) {
  return (
    <RightCenter
      userId={userId}
      apiKey={process.env.NEXT_PUBLIC_TRUCONSENT_ADMIN_API_KEY!}
      organizationId={process.env.NEXT_PUBLIC_TRUCONSENT_ORG_ID!}
    />
  );
}

`RightCenter` props

Prop	Type	Required	Description
`userId`	`string`	Yes	Unique identifier for the authenticated user
`apiKey`	`string`	Yes	Your truConsent API key (admin scope)
`organizationId`	`string`	Yes	Your organization’s unique identifier

Full integration example

The following shows a minimal but complete integration — checking whether a user has already consented and conditionally showing the consent banner.

'use client';

import { useEffect, useState } from 'react';
import { TruConsentModal } from '@truconsent/consent-notice';
import '@truconsent/consent-notice/tailwind.css';

const API_KEY = import.meta.env.VITE_TRUCONSENT_API_KEY;
const ORG_ID = import.meta.env.VITE_TRUCONSENT_ORG_ID;
const BANNER_ID = 'CP001';

export function ConsentGate({
  userId,
  logoUrl,
}: {
  userId: string;
  logoUrl: string;
}) {
  const [needsConsent, setNeedsConsent] = useState(false);

  useEffect(() => {
    fetch(
      `https://api.truconsent.io/consent/user-consent-status?userId=${userId}`,
      {
        headers: {
          'X-API-Key': API_KEY,
          'X-Org-Id': ORG_ID,
        },
      }
    )
      .then((r) => r.json())
      .then((data) => {
        const hasConsent = data.collection_points?.some(
          (cp: { collection_point: { id: string } }) =>
            cp.collection_point.id === BANNER_ID
        );
        setNeedsConsent(!hasConsent);
      });
  }, [userId]);

  if (!needsConsent) return null;

  return (
    <TruConsentModal
      userId={userId}
      apiKey={API_KEY}
      organizationId={ORG_ID}
      bannerId={BANNER_ID}
      logoUrl={logoUrl}
      onClose={() => setNeedsConsent(false)}
    />
  );
}

npm Package

Installation

Core API URLs

Environment configuration

1. Discovery: external API workflow

Step 1: Fetch assets

Step 2: Fetch collection points

2. Consent banner integration

CSS import

Component implementation

TruConsentModal props

3. Rights centre integration

CSS import

Component implementation

RightCenter props

Full integration example

`TruConsentModal` props

`RightCenter` props