useCookieConsent hook for pure JavaScript projects

Headless state management for GDPR cookie consent

Headless - bring your own styles, we will provide the logic.
Hook-based - extremely intuitive for React developers, but can be used in any JavaScript application.
Small - Just under 1.5kB gzipped.

Library-specific packages

This repo was made to be framework-agnostic, so you can use it in any JavaScript project. If you use a UI library that we support, you should use the package for your library for best experience

@use-cookie-consent/react

Description

This package is following this GDPR cookie guide which describes what you need for GDPR compliance. This hook mainly focuses handling the consent state of the different types of cookies as described in "Types of Cookies" in this page. Summarizing the mentioned document, there are three different ways to classify cookies:

Cookie Duration
- Session cookies
- Persistent cookies
Cookie Provenance
- First-party cookies
- Third-party cookies
Cookie Purpose
- Strictly necessary cookies
- Preferences cookies
- Statistics cookies
- Marketing cookies

The hook in this repository will provide a way to manage these types of cookies.

Installation

Using npm:

npm i @use-cookie-consent/core

Using yarn:

yarn add @use-cookie-consent/core

Usage in React

import { useCookieConsent } from '@use-cookie-consent/core';

export const YourComponent = () => {
  const { consent, acceptAllCookies, declineAllCookies, acceptCookies } =
    useCookieConsent();

  return (
    <div>
      <h3>
        {`Third-party cookies ${consent.thirdParty ? 'approved' : 'rejected'}`}
      </h3>
      <h3>
        {`First-party cookies ${consent.firstParty ? 'approved' : 'rejected'}`}
      </h3>

      <button onClick={acceptAllCookies}>Accept all</button>
      <button onClick={() => acceptCookies({ thirdParty: true })}>
        Accept third-party
      </button>
      <button onClick={() => acceptCookies({ firstParty: true })}>
        Accept first-party
      </button>
      <button onClick={declineAllCookies}>Reject all</button>
    </div>
  );
};

API

`useCookieConsent(options)`

useCookieConsent is the main hook in this library. You call it whenever you need to accept, decline, set or get cookies - so anything to do with cookies.

useCookieConsent({
  defaultConsent?: CookieConsent,
  consentCookieAttributes?: CookieAttributes;
})

This hook function returns following object:

{
  consent: {
    session?: boolean;
    persistent?: boolean;
    necessary?: boolean;
    preferences?: boolean;
    statistics?: boolean;
    marketing?: boolean;
    firstParty?: boolean;
    thirdParty?: boolean;
  };
  acceptCookies: (cookies: CookieTypes) => void;
  declineAllCookies: () => void;
  acceptAllCookies: () => void;
  didAcceptAll: () => boolean;
  didDeclineAll: (opts?: CookieDeclineOptions) => boolean;
  cookies: CookieWrapper;
}

Roadmap to v1

Add package bundler (rollup was added)
Add support for Storage API
Add support for custom cookie categories
Create documentation website here
Create supporting library packages
- React here
- Vue (planned)
- Svelte (planned)
Change CookiesWrapper API to something that doesn't require a specific dependency (maybe just Storage API step?)

Acknowledgements

Following package was used as a starter for this project:

easy-npm-package-react

Contributors

Antoni Silvestrovic (author)

License

MIT

emilforsmann / use-cookie-consent-core