NDPR Toolkit Documentation | Implementation Guides & API Reference

Overview

The Consent Management component provides a complete solution for collecting, storing, and managing user consent in compliance with the Nigeria Data Protection Regulation (NDPR). It includes a customizable consent banner, preference management interface, and consent storage system.

NDPR Consent Requirements

Under the NDPR, consent must be freely given, specific, informed, and unambiguous. The data subject must clearly indicate acceptance through a statement or clear affirmative action. Pre-ticked boxes or silence do not constitute valid consent.

Installation

Install the NDPR Toolkit package which includes the Consent Management components:

npm install @tantainnovative/ndpr-toolkit

Or if you're using yarn:

yarn add @tantainnovative/ndpr-toolkit

Components

The Consent Management system includes several components that work together:

ConsentBanner

A cookie consent banner that appears at the bottom of the page when a user first visits your site. Fully customizable with support for multiple consent options.

import { ConsentBanner } from '@tantainnovative/ndpr-toolkit';

<ConsentBanner 
  options={[
    {
      id: 'necessary',
      label: 'Necessary Cookies',
      description: 'Essential cookies for the website to function.',
      required: true
    },
    {
      id: 'analytics',
      label: 'Analytics Cookies',
      description: 'Cookies that help us understand how you use our website.',
      required: false
    },
    {
      id: 'marketing',
      label: 'Marketing Cookies',
      description: 'Cookies used for marketing purposes.',
      required: false
    }
  ]}
  onSave={(consents) => console.log(consents)}
  position="bottom"
  showPreferences={true}
  privacyPolicyUrl="/privacy-policy"
/>

ConsentPreferences

A detailed interface for users to manage their consent preferences after the initial consent has been given.

import { ConsentPreferences } from '@tantainnovative/ndpr-toolkit';

<ConsentPreferences 
  options={consentOptions}
  currentConsent={currentConsent}
  onSave={handleSaveConsent}
  onReset={handleResetConsent}
/>

ConsentManager

A higher-order component that manages the consent state and provides methods for checking and updating consent. Works with the useConsent hook to provide a complete consent management solution.

import { ConsentManager, useConsent } from '@tantainnovative/ndpr-toolkit';

function App() {
  return (
    <ConsentManager
      options={[
        {
          id: 'necessary',
          label: 'Necessary Cookies',
          description: 'Essential cookies for the website to function.',
          required: true
        },
        {
          id: 'analytics',
          label: 'Analytics Cookies',
          description: 'Cookies that help us understand how you use our website.',
          required: false
        }
      ]}
      storageKey="my-app-consent"
      autoLoad={true}
      autoSave={true}
    >
      <MyApp />
    </ConsentManager>
  );
}

function MyApp() {
  const { 
    consents, 
    hasConsented, 
    updateConsent,
    saveConsents,
    resetConsents 
  } = useConsent();
  
  // Check if user has given consent for analytics
  if (hasConsented('analytics')) {
    // Initialize analytics
  }
  
  return (
    <div>
      {/* Your app content */}
      <button onClick={() => updateConsent('analytics', true)}>Enable Analytics</button>
    </div>
  );
}

ConsentStorage

A component for handling the storage and retrieval of consent settings. Supports both local storage and custom storage mechanisms.

import { ConsentStorage, ConsentSettings } from '@tantainnovative/ndpr-toolkit';
import { useState } from 'react';

function ConsentStorageExample() {
  const [settings, setSettings] = useState<ConsentSettings>({
    necessary: true,
    analytics: false,
    marketing: false,
    lastUpdated: Date.now()
  });

  const handleLoad = (loadedSettings: ConsentSettings | null) => {
    if (loadedSettings) {
      setSettings(loadedSettings);
    }
  };

  return (
    <ConsentStorage
      settings={settings}
      storageOptions={{
        key: 'my-app-consent',
        storage: 'localStorage' // or 'sessionStorage' or 'cookie'
      }}
      onLoad={handleLoad}
      onSave={(savedSettings) => console.log('Saved:', savedSettings)}
      autoLoad={true}
      autoSave={true}
    >
      {/* Render prop pattern */}
      {({ loadSettings, saveSettings, clearSettings, loaded }) => (
        <div>
          <p>Consent settings loaded: {loaded ? 'Yes' : 'No'}</p>
          <button onClick={() => saveSettings(settings)}>Save Settings</button>
          <button onClick={() => clearSettings()}>Clear Settings</button>
        </div>
      )}
    </ConsentStorage>
  );
}

Usage

Here's a complete example of how to implement the consent management system in your application:

import { useState, useEffect } from 'react';
import { 
  ConsentBanner, 
  ConsentPreferences, 
  ConsentManager, 
  ConsentStorage,
  useConsent 
} from '@tantainnovative/ndpr-toolkit';

// Define your consent options
const consentOptions = [
  {
    id: 'necessary',
    label: 'Necessary Cookies',
    description: 'Essential cookies for the website to function.',
    required: true
  },
  {
    id: 'analytics',
    label: 'Analytics Cookies',
    description: 'Cookies that help us understand how you use our website.',
    required: false
  },
  {
    id: 'marketing',
    label: 'Marketing Cookies',
    description: 'Cookies used for marketing purposes.',
    required: false
  }
];

function App() {
  const [showPreferences, setShowPreferences] = useState(false);
  
  return (
    <ConsentManager
      options={consentOptions}
      storageKey="my-app-consent"
    >
      <div>
        {/* Your app content */}
        <header>
          <nav>
            {/* ... */}
            <button onClick={() => setShowPreferences(true)}>
              Cookie Preferences
            </button>
          </nav>
        </header>
        
        <main>
          {/* Your main content */}
        </main>
        
        {/* Cookie preferences modal */}
        {showPreferences && (
          <PreferencesModal 
            onClose={() => setShowPreferences(false)} 
          />
        )}
        
        {/* Consent banner */}
        <ConsentBanner 
          options={consentOptions}
          position="bottom"
          privacyPolicyUrl="/privacy-policy"
        />
      </div>
    </ConsentManager>
  );
}

function PreferencesModal({ onClose }) {
  const { 
    consents, 
    updateConsent, 
    saveConsents, 
    resetConsents 
  } = useConsent();
  
  const handleSave = () => {
    saveConsents();
    onClose();
  };
  
  return (
    <div className="modal">
      <div className="modal-content">
        <h2>Cookie Preferences</h2>
        <ConsentPreferences 
          options={consentOptions}
          currentConsent={consents}
          onSave={handleSave}
          onReset={resetConsents}
        />
        <button onClick={onClose}>Cancel</button>
      </div>
    </div>
  );
}

// Example of using the useConsent hook to check consent
function AnalyticsComponent() {
  const { hasConsented } = useConsent();
  
  useEffect(() => {
    if (hasConsented('analytics')) {
      // Initialize analytics
      console.log('Analytics initialized');
    }
  }, [hasConsented]);
  
  return null;
}

API Reference

ConsentBanner Props

Prop	Type	Default	Description
options	ConsentOption[]	Required	Array of consent options to display
onSave	({ consents: Record<string, boolean> }) => void	Required	Callback function called when consent is saved
position	'top' \| 'bottom'	'bottom'	Position of the banner on the page
title	string	'Cookie Consent'	Title displayed on the banner
description	string	'We use cookies...'	Description text explaining the purpose of cookies
showPreferences	boolean	true	Whether to show the "Preferences" button
privacyPolicyUrl	string	undefined	URL to the privacy policy page

ConsentStorage Props

Prop	Type	Default	Description
settings	ConsentSettings	Required	Current consent settings to store
storageOptions	ConsentStorageOptions	{ storageKey: 'ndpr_consent', storageType: 'localStorage' }	Options for storage mechanism
onLoad	(settings: ConsentSettings \| null) => void	undefined	Callback when settings are loaded
onSave	(settings: ConsentSettings) => void	undefined	Callback when settings are saved
autoLoad	boolean	true	Whether to load settings on mount
autoSave	boolean	true	Whether to save settings automatically
children	ReactNode \| Function	undefined	React nodes or render prop function

ConsentOption Type

type ConsentOption = {
  id: string;
  label: string;
  description: string;
  required?: boolean;
};

ConsentSettings Type

type ConsentSettings = {
  [key: string]: boolean;
  lastUpdated: number;
};

ConsentStorageOptions Type

type ConsentStorageOptions = {
  key: string;
  storage: 'localStorage' | 'sessionStorage' | 'cookie';
  cookieOptions?: {
    path?: string;
    domain?: string;
    secure?: boolean;
    sameSite?: 'strict' | 'lax' | 'none';
    maxAge?: number;
  };
};

Best Practices

Clear Language: Use clear, plain language to explain what each type of cookie does and why you're collecting the data.
No Pre-selected Options: Don't pre-select non-essential cookies. The NDPR requires that consent is freely given and pre-selected checkboxes don't constitute valid consent.
Easy Access to Preferences: Make it easy for users to access and update their consent preferences at any time.
Consent Records: Keep records of when and how consent was obtained. The ConsentManager component automatically tracks consent history.
Respect User Choices: Only activate cookies and tracking technologies when the user has given explicit consent for them.

Accessibility

The Consent Management components are built with accessibility in mind:

All form elements have proper labels and ARIA attributes
Focus states are clearly visible
Color contrast meets WCAG 2.1 AA standards
Keyboard navigation is fully supported
The banner is announced to screen readers when it appears

Need Help?

If you have questions about implementing the Consent Management system or need assistance with NDPR compliance, check out these resources:

GitHub Issues

Report bugs or request features on our GitHub repository.

View Issues

NDPR Resources

Learn more about NDPR compliance requirements.

NDPR Framework