Home
A React library for cookie consent management that actually blocks tracking scripts until users give consent.
Most cookie consent solutions only show a banner and hope for the best. They don't actually prevent scripts from running before the user makes a choice. This means that by the time a user clicks "Reject All", Google Analytics has already tracked their visit, Meta Pixel has already fired, and their data is already on its way to servers around the world.
react-consent-shield works differently. It intercepts script loading at the DOM level, preventing analytics, marketing, and tracking scripts from executing until explicit consent is given. This is real compliance, not just a checkbox exercise.
Privacy regulations like GDPR, CCPA, and LGPD require informed consent before collecting personal data. But implementing this correctly is surprisingly hard:
- Scripts load before your React app renders - By the time your consent banner appears, tracking has already started
- Third-party scripts inject more scripts - Blocking one script doesn't block the scripts it loads
- Different laws have different rules - GDPR requires opt-in, CCPA allows opt-out, some regions have no requirements at all
- Google needs special signals - Google Consent Mode v2 requires specific consent signals to work correctly
This library solves all of these problems with a single provider component and zero configuration for common use cases.
Unlike CSS-based "blocking" that just hides content, this library uses a MutationObserver to intercept script tags as they're added to the DOM. Scripts are converted to inert data-blocked elements until consent is granted, then restored to their original form.
The library detects your user's location and automatically applies the correct privacy law. A visitor from Germany gets GDPR rules (opt-in required), a visitor from California gets CCPA rules (opt-out allowed), and a visitor from a region without privacy laws can skip the banner entirely.
Google Analytics, Meta Pixel, TikTok Pixel, Hotjar, Mixpanel, Amplitude, Segment, Microsoft Clarity... the list goes on. Each service preset includes the correct script patterns, cookie names, and consent categories. Just import and use.
Getting started takes less than a minute:
npm install react-consent-shieldimport {
ConsentProvider,
ConsentBanner,
ConsentModal,
googleAnalytics,
metaPixel,
} from 'react-consent-shield';
function App() {
return (
<ConsentProvider
config={{
services: [googleAnalytics, metaPixel],
}}
>
<YourApp />
<ConsentBanner />
<ConsentModal />
</ConsentProvider>
);
}That's it. The banner appears, scripts are blocked until consent, and preferences are persisted automatically.
You're running an online store and need conversion tracking for marketing campaigns, heat maps to understand user behavior, and compliance with multiple privacy laws depending on where your customers are located.
<ConsentProvider
config={{
services: [googleAnalytics, metaPixel, hotjar],
geoDetection: { enabled: true },
}}
>The library automatically detects whether to show opt-in (GDPR) or opt-out (CCPA) flows based on the visitor's location.
Your users are privacy-conscious and want to choose exactly which services to enable. With granular consent, they can allow product analytics while blocking marketing pixels.
<ConsentProvider
config={{
services: [mixpanel, amplitude, segment, microsoftClarity],
granularConsent: true,
}}
>Your application serves users worldwide. The library handles the complexity of applying the correct rules for each jurisdiction, with a fallback to the strictest rules when detection fails.
<ConsentProvider
config={{
services: [googleAnalytics],
geoDetection: {
enabled: true,
fallbackLaw: 'GDPR', // Default to strictest
},
}}
>If your site is accessible to minors, you need age verification before collecting any data. The library supports checkbox, year-of-birth, and full birthdate verification methods.
<ConsentProvider
config={{
services: [googleAnalytics],
ageVerification: {
enabled: true,
method: 'birthdate',
minimumAge: 16,
},
}}
>| Feature | What It Does |
|---|---|
| Real Script Blocking | Intercepts scripts at the DOM level, not just CSS hiding |
| 52 Privacy Laws | GDPR, CCPA, LGPD, POPIA, PDPA, and 47 regional variations |
| 274 Service Presets | Google, Meta, TikTok, Hotjar, and hundreds more ready to use |
| Google Consent Mode v2 | Automatic consent signal updates for Google services |
| Cookie Scanner | Detects undeclared cookies for compliance auditing |
| Audit Logging | Cryptographically verified records of every consent action |
| 10 Languages | English, Spanish, German, French, Portuguese, Italian, Dutch, Polish, Japanese, Chinese |
| WCAG 2.2 AA | Full keyboard navigation, screen reader support, focus management |
| 8 Banner Variants | Bottom bar, modal, floating, corner popup, sidebar, and more |
- Getting-Started - Installation and basic setup
- Configuration - All provider, banner, and modal options
- Frameworks - Next.js, Vite, plain HTML examples
- Components - ConsentProvider, ConsentBanner, ConsentModal, ConsentScript
- Hooks - useConsent, useConsentCategory, useConsentService, useGeoDetection
- Service-Presets - All 274 pre-configured services and how to create custom ones
- Script-Blocking - How the blocking mechanism works under the hood
- Granular-Consent - Let users choose individual services, not just categories
- Google-Consent-Mode - Full integration with Google's consent framework
- Geo-Detection - Automatic privacy law detection based on location
- Cookie-Scanner - Find undeclared cookies before auditors do
- Audit-Logging - Tamper-proof records for compliance documentation
- Compliance-Report - Generate technical reports for privacy audits
- Consent-Versioning - Automatically re-prompt when services change
- Subdomain-Sharing - Share consent across your entire domain
- i18n - Internationalization and custom translations
- Age-Verification - COPPA and GDPR-K compliance for sites with minors
- GDPR - European Union (27 countries)
- UK-GDPR - United Kingdom
- CCPA - California, USA
- US-State-Laws - Virginia, Colorado, Connecticut, and other US states
- LGPD - Brazil
- PIPEDA - Canada
- POPIA - South Africa
- Asia-Pacific - PDPA (Singapore, Thailand), PIPL (China), and more
- Latin-America - Argentina, Chile, Colombia, Mexico, and more
- Middle-East - UAE, Saudi Arabia, Israel, and more
- Russia - Russian Federation data localization
- Styling - CSS variables and complete customization examples
- Performance - Optimization tips for large-scale deployments
- Accessibility - WCAG compliance details and testing
- Security - Security considerations and best practices
- Troubleshooting - Common issues and solutions
The best way to understand the library is to see it in action. The interactive demo lets you:
- Switch between all 8 banner variants
- Test different geographic locations and privacy laws
- See how consent signals are sent to Google
- Scan for cookies in real-time
- Generate compliance reports
- npm: npmjs.com/package/react-consent-shield
- Demo: react-consent-shield.onrender.com
- GitHub: github.com/686f6c61/react-consent-shield
- Issues: Report bugs or request features
PolyForm Noncommercial License 1.0.0
This library is free for personal projects, learning, education, non-profit organizations, and open source development.
Commercial use (websites with ads, SaaS products, e-commerce, any for-profit use) requires a separate license. Contact us on GitHub for commercial licensing options.