react-lgpd-consent 🍪

A React library for cookie consent management compliant with Brazil's LGPD.

Installation • Basic Usage • 📚 Quickstart • Documentation • Contributing

Start here: follow the Quickstart guide (QUICKSTART.en.md) for step-by-step setup, TypeScript examples, props summary and MUI integration — recommended for new users.

🚀 Installation

npm install react-lgpd-consent @mui/material @emotion/react @emotion/styled js-cookie

Peer dependencies: react, react-dom, @mui/material and js-cookie.

📖 Basic Usage

Wrap your app with ConsentProvider (minimal example):

import { ConsentProvider } from 'react-lgpd-consent'

export default function App() {
  return (
    <ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
      <YourApp />
    </ConsentProvider>
  )
}

For full guides, TypeScript examples, props table and integrations see:
QUICKSTART.en.md (recommended)
- New in v0.4.0: customCategories support — see the “Custom categories (customCategories)” section in the Quickstart.
- New in v0.4.1: native integrations for Facebook Pixel, Hotjar, Mixpanel, Clarity, Intercom, and Zendesk — see INTEGRACOES.md.
- Tip: set designTokens.layout.backdrop: 'auto' for a theme-aware blocking banner backdrop.
- Auto-config of categories: the library detects required categories from integrations and surfaces toggles even if you forgot to enable them (initial value is always rejected). We still recommend explicitly listing them in categories.enabledCategories for clarity.
- Non-blocked Policy/Terms pages: if policyLinkUrl and/or termsLinkUrl point to the current page, the blocking overlay is not applied — ensuring readability of these pages.
Docs / API
LGPD Compliance
Integrations

🎨 Interactive Documentation (GitHub Pages)

📖 Storybook - Interactive Playground: Explore and test all components live with interactive controls.
⚙️ TypeDoc - API Reference: Automatically generated complete API documentation.
🏠 Documentation Portal: Home page that navigates between all docs sites.

🧑‍🏫 Developer Guidance (dev-only)

In development, the library prints a guidance panel in the console to help you configure correctly:

Warns when using default categories; suggests making them explicit
Lists active categories and which ones require a UI toggle
Detects integrations that require categories and suggests enabling them
Flags excessive number of categories (UX)
Highlights Brazilian LGPD best practices: opt-out by default, clear policy, consent logging, retention
Silenced in production; SSR-safe

⚠️ Breaking Changes v0.4.1

Custom categories support: setPreference and ScriptIntegration.category now use string instead of Category
Minimal impact: Code using literal strings continues working without changes
Migration guide: See CHANGELOG.md for complete details

🤝 Contributing

Open an Issue for bugs or feature requests.
Follow DEVELOPMENT.md to submit a PR.

📄 License

MIT — see the LICENSE file.