react-cookiefirst

A simple React component for loading and interacting with CookieFirst banner.

Installation

yarn add react-cookiefirst
// or
npm install react-cookiefirst

Usage

import ReactCookieFirst from "react-cookiefirst";

Then you can use it as a standalone component to simply load the banner

<ReactCookieFirst apiKey="XXXXXX" />

Or as a context provider to get access to current consent state and various methods

<ReactCookieFirst apiKey="XXXXXX">
  <SomeContextConsumer />
  {/* some other components */}
</ReactCookieFirst>

SomeContextConsumer.jsx file:

import { useCookieFirst } from "react-cookiefirst";

const SomeContextConsumer = () => {
  const context = useCookieFirst();

  // ...
};

ReactCookieFirst props

Name	Type	Default	Description
apiKey	string	""	API key coming from cookiefirst.com panel
silent	boolean	false	Silent mode to hide all CookieFirst console logs
stealth	boolean	false	Stealth mode to hide default banner UI. Use with custom banner
lang	string	undefined	Force banner UI texts in a given language. E.g. lang="de"
renderBeforeReady	boolean	false	Enable this to render component's children before CookieFirst banner is loaded

Context

When using the useCookieFirst context hook, the returned value is an object with the following properties:

Name	Type	Description
consent	null or Consent	Current user's consent. Will be null before user consents for the first time.
openPanel	function	opens the settings panel / modal. Unavailable in stealth mode
closePanel	function	closes the settings panel / modal. Unavailable in stealth mode
updateConsent	async function	Takes as an argument the new Consent and saves it
acceptCategory	async function	Takes as an argument name of a cookie category and saves consent with this category accepted
acceptAllCategories	async function	Saves consent with all categories accepted
acceptPreselectedCategories	async function	Saves consent with only preselected categories from the cookiefirst admin panel
declineAllCategories	async function	Saves consent with all categories rejected
declineCategory	async function	Takes as an argument name of a cookie category and saves consent with this category rejected
withdrawConsent	async function	Withdraws previous consent. Can be used only after consent is given.

⚠️ All of the consent-changing functions will trigger a page reload if there was a previously saved consent. This is done because on initialization CookieFirst banner checks accepted categories and loads respective scripts. There is no way to "unload" a script once it's loaded.

The consent object

The consent object has the following structure:

{
  necessary: boolean;
  performance: boolean;
  functional: boolean;
  advertising: boolean;
}

This is the object which is available under consent property of the object returned by useCookieFirst hook. This is also the structure expected by the updateConsent function. Example:

const ctx = useCookieFirst();
console.log(ctx.consent);
/*
{
  necessary: true;
  performance: true;
  functional: false;
  advertising: false;
}
*/

ctx.updateConsent({
  ...ctx.consent,
  functional: true,
});

// website reloads because there was previous consent

The acceptCategory and declineCategory functions expect to be passed a key from the consent object. For example

const ctx = useCookieFirst();
ctx.acceptCategory("performance");
// no window reload if this is the first consent, reload if not the first consent