@afex-dapps/cookie
Version:
Cookie Consent library for React
1,829 lines (1,815 loc) • 53.2 kB
text/typescript
import { FirebaseOptions } from 'firebase/app';
import { CookieItem, Service, AcceptType, ConsentModalLayout, ConsentModalPosition, PreferencesModalLayout, PreferencesModalPosition, CookieValue, ModalName, UserPreferences } from 'vanilla-cookieconsent';
import { Keyframes, CSSPropertiesWithMultiValues } from '@emotion/serialize';
import { Pseudos } from 'csstype';
/**
* Bind any button or link to the consent manager using the `data-cc` attribute.
* This allows you to trigger the consent manager from anywhere on your website.
* The value of the `data-cc` attribute should be one of the predefined values.
*/
declare const cookieConsentAttributes: {
/**
* @description
* Use this value to accept all cookie categories.
*
* @example
*
* ```html
* <button type="button" data-cc="accept-all">Accept all categories</button>
* <a href="#" data-cc={cookieConsentAttributes.acceptAll}>Accept all categories</a>
* ```
*/
acceptAll: string;
/**
* @description
* Use this value to accept the current selection inside the preferences modal.
*
* @example
*
* ```html
* <button type="button" data-cc="accept-custom">Accept selection</button>
* <a href="#" data-cc={cookieConsentAttributes.acceptCustom}>Accept selection</a>
* ```
*/
acceptCustom: string;
/**
* @description
* Use this value to accept only the necessary cookie categories.
*
* @example
*
* ```html
* <button type="button" data-cc="accept-necessary">Reject all categories</button>
* <a href="#" data-cc={cookieConsentAttributes.acceptNecessary}>Reject all categories</a>
* ```
*/
acceptNecessary: string;
/**
* @description
* Use this value to show the consentModal. If the consent modal does not exist, it will be generated on the fly.
*
* @example
*
* ```html
* <button type="button" data-cc="show-consentModal">View Consent Modal</button>
* <a href="#" data-cc={cookieConsentAttributes.showConsentModal}>View Consent Modal</a>
* ```
*/
showConsentModal: string;
/**
* @description
* Use this value to show the preferencesModal.
*
* @example
*
* ```html
* <button type="button" data-cc="show-preferencesModal">View Preferences Modal</button>
* <a href="#" data-cc={cookieConsentAttributes.showPreferencesModal}>View Preferences Modal</a>
* ```
*/
showPreferencesModal: string;
};
declare const cookieConsentEvents: {
/**
* @description
* This event is triggered when the user modifies their preferences and only if consent has already been provided.
*
* @example
*
* ```js
* cookieConsentEvents.onChange // "cc:onChange"
* window.addEventListener('cc:onChange', ({ detail }) => {
* // detail.cookie
* // detail.changedCategories
* // detail.changedServices
* });
* ```
*/
onChange: string;
/**
* @description
* This event is triggered the very first time the user expresses their choice of consent — just like onFirstConsent — but also on every subsequent page load.
*
* @example
*
* ```js
* cookieConsentEvents.onConsent // "cc:onConsent"
* window.addEventListener('cc:onConsent', ({ detail }) => {
* // detail.cookie
* });
* ```
*/
onConsent: string;
/**
* @description
* This event is triggered only the very first time that the user expresses their choice of consent (accept/reject).
*
* @example
*
* ```js
* cookieConsentEvents.onFirstConsent // "cc:onFirstConsent"
* window.addEventListener('cc:onFirstConsent', ({ detail }) => {
* // detail.cookie
* });
* ```
*/
onFirstConsent: string;
/**
* @description
* This event is triggered when one of the modals is hidden.
*
* @example
*
* ```js
* cookieConsentEvents.onModalHide // "cc:onModalHide"
* window.addEventListener('cc:onModalHide', ({ detail }) => {
* // detail.modalName
* });
* ```
*/
onModalHide: string;
/**
* @description
* This event is triggered when a modal is created and appended to the DOM.
*
* @example
*
* ```js
* cookieConsentEvents.onModalReady // "cc:onModalReady"
* window.addEventListener('cc:onModalReady', ({ detail }) => {
* // detail.modalName
* // detail.modal
* });
* ```
*/
onModalReady: string;
/**
* @description
* This event is triggered when one of the modals is visible.
*
* @example
*
* ```js
* cookieConsentEvents.onModalShow // "cc:onModalShow"
* window.addEventListener('cc:onModalShow', ({ detail }) => {
* // detail.modalName
* });
* ```
*/
onModalShow: string;
};
/**
* ### Available [Callbacks and Events](https://cookieconsent.orestbida.com/advanced/callbacks-events.html)
*
* There are a few callbacks/events at your disposal to handle different kinds of situations.
* Each callback has a corresponding custom event, named after the callback function itself.
*
* **Valid values:**
*
* - `onFirstConsent`
* - `onConsent`
* - `onChange`
* - `onModalShow`
* - `onModalHide`
* - `onModalReady`
*
* ---
*
* ### Available [data-attributes](https://cookieconsent.orestbida.com/advanced/custom-attribute.html)
*
* The `data-cc` attribute allows you to bind any `button` — or `link` — to a few API methods in order to run core functions, without the need to use javascript code.
*
* **Valid values:**
*
* - `show-preferencesModal`
* - `show-consentModal`
* - `accept-all`
* - `accept-necessary`
* - `accept-custom`
*/
interface CookieConsentConfiguration {
/**
* Clears cookies when user rejects a specific category. It requires a valid autoClear array.
*
* ---
*
* **Default:** `true`
*
* ---
*
* **Type:** `boolean`
*
* ---
*
* **Details:**
*
* This function is executed on the following 2 events:
*
* - when consent is not valid and the onFirstConsent callback is executed
* - when consent is valid and the state of the categories is changed
*/
autoClearCookies?: boolean;
/**
* Automatically shows the consent modal if consent is not valid.
*
* ---
*
* **Default:** `true`
*
* ---
*
* **Type:** `boolean`
*
* ---
*
* **Details:**
*
* When set to `true`, the consent modal will automatically appear if the user's consent is not valid.
* If set to `false`, the modal will not appear automatically and must be triggered manually.
*
* ---
*
* **Example:**
*
* Disable `autoShow` and display the modal after 3 seconds:
*
* ```typescript
* CookieConsent.run({
* autoShow: false
* });
*
* setTimeout(CookieConsent.show, 3000);
* ```
*/
autoShow?: boolean;
/**
* Configure cookie categories.
*/
categories: {
[key: string]: Category;
};
/**
* Change plugin's default cookie options.
*/
cookie?: CookieOptions;
/**
* Create dark overlay and disable page scroll until consent.
*
* @default false
*/
disablePageInteraction?: boolean;
/**
* Tweak some UI options.
*/
guiOptions?: GuiOptions;
/**
* Stop the plugin's execution if a bot/crawler is detected
* to prevent the indexing of the modal's content.
*
* @default true
*/
hideFromBots?: boolean;
/**
* Configure language and translations.
*/
language: {
/**
* Set the current language dynamically.
*
* ---
*
* **Type:** `string`
*
* ---
*
* **Details:**
*
* The language will be set only if a valid translation is defined, otherwise the plugin will fallback to the default language.
*
* ---
*
* **Valid values:**
*
* - `document`: retrieve language from the lang attribute (e.g. <html lang="en-US">)
* - `browser`: retrieve the user's browser language via navigator.language
*/
autoDetect?: "browser" | "document";
/**
* The desired default language.
*
* ---
*
* **Type:** `string`
*
* ---
*
* **Example:**
*
* ```typescript
* CookieConsent.run({
* language: {
* default: "en"
* }
* })
* ```
*/
default: string;
/**
* List of languages that should use the RTL layout.
*
* ---
*
* **Type:** `string | string[]`
*
* ---
*
* **Details:**
*
* The RTL layout will be applied to the specified languages.
*
* ---
*
* **Example:**
*
* ```typescript
* CookieConsent.run({
* language: {
* default: "en",
* rtl: "ar" // enable RTL for Arabic
* autoDetect: "browser",
* translations: {
* en: "/assets/translations/en.json",
* ar: "/assets/translations/ar.json"
* }
* }
* })
*/
rtl?: string | string[];
/**
* Define the translation(s) content.
*
* **Type:**
*
* ```typescript
* interface Translations {
* [locale: string]:
* Translation
* | string
* | (() => Translation)
* | (() => Promise<Translation>)
* }
* ```
*
* ---
*
* **Details:**
*
* You can define an inline translation object, or specify the path to an external .json translation file.
*
* ---
*
* **Examples:**
*
* ---
*
* External translation file:
*
* @example
*
* ```typescript
* CookieConsent.run({
* language: {
* default: "en",
* translations: {
* en: "/assets/translations/en.json"
* }
* }
* })
* ```
*
* ---
*
* Inline translation object:
*
* @example
*
* ```typescript
* CookieConsent.run({
* language: {
* default: "en",
* translations: {
* en: {
* consentModal: {
* // ...
* },
* preferencesModal: {
* // ...
* }
* }
* }
* }
* })
* ```
*
* ---
*
* You can also fetch a translation asynchronously:
*
* @example
*
* ```typescript
* CookieConsent.run({
* language: {
* default: "en",
* translations: {
* en: async () => {
* const res = fetch("path-to-json-translation");
* return await res.json();
* }
* }
* }
* })
* ```
*/
translations: {
[locale: string]: (() => Promise<Translation>) | (() => Translation) | string | Translation;
};
};
/**
* Delays the generation of the modal's markup until they're about to become visible, to improve the TTI score.
* You can detect when a modal is ready/created via the `onModalReady` callback.
*
* @default true
*/
lazyHtmlGeneration?: boolean;
/**
* Intercept all `<script>` tags with a `"data-category"` attribute, and enables them based on the accepted categories.
*
* ---
*
* **Default:** true
*
* ---
*
* **Type:** `boolean`
*
* ---
*
* **Details:**
*
* There are two ways to manage your scripts:
*
* - via <script> tags
* - via callbacks/events
*
* ---
*
* **Info:**
*
* A `<script>` tag can be enabled and disabled at most once, unlike the `onChange` callback — or its equivalent event listener — which can be executed multiple times.
*
* ---
*
* **Available script attributes:**
*
* - **`data-category`**: name of the category
* - **`data-service` (optional)**: if specified, a toggle will be generated in the `preferencesModal`
* - **`data-type` (optional)**: custom type (e.g. "module")
* - **`data-src` (optional)**: can be used instead of src to avoid validation issues
*
* ---
*
* **Example:**
*
* You can manage any script tag by adding the following 2 attributes (both required):
*
* - type="text/plain"
* - data-category="your-category-name"
*
* ---
*
* **Inline script for enabled category:**
*
* ```html
* <script
* type="text/plain"
* data-category="analytics"
* data-service="Google Analytics"
* >
* // Executed when the "analytics" category is enabled
* </script>
* ```
*
* ---
*
* **Inline script for disabled category:**
*
* You can also run scripts when a category is disabled (if it was previously enabled) by prepending the "!" character to the category name:
*
* ```html
* <script
* type="text/plain"
* data-category="!analytics"
* >
* // Executed when the "analytics" category is disabled
* </script>
* ```
*
* ---
*
* **External script with src attribute:**
*
* You can set a custom script type via the `data-type` attribute. E.g. to set the `type="module"` attribute you must specify `data-type="module"`:
*
* ```html
* <script
* type="text/plain"
* data-src="https://www.googletagmanager.com/gtag/js?id=UA-XXXXXX-X"
* data-category="analytics"
* data-service="Google Analytics"
* data-type="module"
* ></script>
* ```
*/
manageScriptTags?: boolean;
/**
* Changes the scripts" activation logic when consent is not valid.
*
* ---
*
* **Default:** "opt-in"
*
* **Type:** `string`
*
* ---
*
* **Values:** `"opt-in" | "opt-out"`
*
* ---
*
* **Details:**
*
* - **`opt-in`**: Scripts — configured under a specific category — will run only if the user accepts that category (GDPR compliant).
* - **`opt-out`**: Scripts — configured under a specific category which has `enabled: true` — will run automatically (it is generally not GDPR compliant). Once the user has provided consent, this option is ignored.
*
* ---
*
* **Example:**
*
* Setting the mode on a per-country basis (concept):
*
* ```typescript
* const euCountries = ["DE", "FR", "IT", ...];
* const userCountry = "IT";
*
* const dynamicMode = euCountries.includes(userCountry) ? "opt-in" : "opt-out";
*
* CookieConsent.run({
* mode: dynamicMode
* });
* ```
*/
mode?: "opt-in" | "opt-out";
/**
* Callback function executed when the user's preferences — such as `accepted categories` and `services` — change.
*
* ---
*
* **Type:**
*
* ```typescript
* function({
* cookie: CookieValue,
* changedCategories: string[],
* changedPreferences: { [category: string]: string[] }
* }): void
* ```
*
* ---
*
* **Details:**
*
* This callback function is executed every time the user changes their preferences in the preferences modal.
* It is useful for tracking or logging purposes, or for executing any other action that should happen every time the user interacts with the preferences modal.
*
* ---
*
* **Example:**
*
* ```typescript
* CookieConsent.run({
* onChange: ({ cookie, changedCategories, changedPreferences }) => {
* if (changedCategories.includes("analytics")) {
*
* if (CookieConsent.acceptedCategory("analytics")) {
* // the analytics category was just enabled
* } else {
* // the analytics category was just disabled
* }
*
* if (changedServices["analytics"].includes("Google Analytics")) {
* if (CookieConsent.acceptedService("Google Analytics", "analytics")) {
* // Google Analytics was just enabled
* } else {
* // Google Analytics was just disabled
* }
* }
* }
* }
* })
* ```
*
* ---
*
* **Using event listener:**
*
* ```typescript
* window.addEventListener("cc:onChange", ({ detail }) => {
* // detail.cookie
* // detail.changedCategories
* // detail.changedServices
* });
* ```
*/
onChange?: (param: {
changedCategories: string[];
changedServices: {
[key: string]: string[];
};
cookie: CookieValue;
}) => void;
/**
* Callback function executed on the user's first consent action and after each page load.
*
* ---
*
* **Type:**
*
* ```typescript
* function({
* cookie: CookieValue
* }): void
* ```
*
* ---
*
* **Details:**
*
* This callback function is executed every time the user accepts or rejects the cookie consent. This callback function is also executed on revision change.
* It is useful for tracking or logging purposes, or for executing any other action that should happen every time the user interacts with the consent modal.
*
* ---
*
* **Example:**
*
* ```typescript
* CookieConsent.run({
* onConsent: ({ cookie }) => {
* if(CookieConsent.acceptedCategory("analytics")){
* // Analytics category enabled
* }
*
* if(CookieConsent.acceptedService("Google Analytics", "analytics")){
* // Google Analytics enabled
* }
* }
* })
* ```
*
* ---
*
* **Using event listener:**
*
* ```typescript
* window.addEventListener("cc:onConsent", ({ detail }) => {
* // detail.cookie
* });
* ```
*/
onConsent?: (param: {
cookie: CookieValue;
}) => void;
/**
* Callback function executed once, on the user's first consent action.
*
* ---
*
* **Type:**
*
* ```typescript
* function({
* cookie: CookieValue
* }): void
* ```
*
* ---
*
* **Details:**
*
* This callback function is executed only once, when the user first accepts or rejects the cookie consent. This callback function is also executed on revision change.
* It is useful for tracking or logging purposes, or for executing any other action that should only happen once.
*
* ---
*
* **Example:**
*
* ```typescript
* CookieConsent.run({
* onFirstConsent: ({ cookie }) => {
* // do something
* }
* })
* ```
*
* ---
*
* **Using event listener:**
*
* ```typescript
* window.addEventListener("cc:onFirstConsent", ({ detail }) => {
* // detail.cookie
* });
* ```
*/
onFirstConsent?: (param: {
cookie: CookieValue;
}) => void;
/**
* Callback function executed when one of the modals is hidden.
*
* ---
*
* **Type:**
*
* ```typescript
* function({
* modalName: ModalName
* }): void
* ```
*
* ---
*
* **Details:**
*
* modalName equals to one of the following values:
*
* - "consentModal"
* - "preferencesModal"
*
* ---
*
* **Example:**
*
* ```typescript
* CookieConsent.run({
* onModalHide: ({ modalName }) => {
* // do something
* }
* })
* ```
*
* ---
*
* **Using event listener:**
*
* ```typescript
* window.addEventListener("cc:onModalHide", ({ detail }) => {
* // detail.modalName
* });
* ```
*/
onModalHide?: (param: {
modalName: ModalName;
}) => void;
/**
* Callback function executed when one of the modals is created and appended to the DOM.
*
* ---
*
* **Type:**
*
* ```typescript
* function({
* modalName: ModalName,
* modal: HTMLElement
* }): void
* ```
*
* ---
*
* **Details:**
*
* modalName equals to one of the following values:
*
* - "consentModal"
* - "preferencesModal"
*
* ---
*
* **Example:**
*
* ```typescript
* CookieConsent.run({
* onModalReady: ({ modalName, modal }) => {
* // do something
* // e.g. modal.classList.add("my-custom-class");
* }
* })
* ```
*
* ---
*
* **Using event listener:**
*
* ```typescript
* window.addEventListener("cc:onModalReady", ({ detail }) => {
* // detail.modalName
* // detail.modal
* });
* ```
*/
onModalReady?: (param: {
modal: HTMLElement;
modalName: ModalName;
}) => void;
/**
* Callback function executed when one of the modals is visible.
*
* ---
*
* **Type:**
*
* ```typescript
* function({
* modalName: ModalName
* }): void
* ```
*
* ---
*
* **Details:**
*
* modalName equals to one of the following values:
*
* - "consentModal"
* - "preferencesModal"
*
* ---
*
* **Example:**
*
* ```typescript
* CookieConsent.run({
* onModalShow: ({ modalName }) => {
* // do something
* }
* })
* ```
*
* ---
*
* **Using event listener:**
*
* ```typescript
* window.addEventListener("cc:onModalShow", ({ detail }) => {
* // detail.modalName
* });
* ```
*/
onModalShow?: (param: {
modalName: ModalName;
}) => void;
/**
* Manages consent revisions; useful if you'd like to ask your users again for consent after a change in your cookie/privacy policy.
*
* ---
*
* **Default:** `0`
*
* ---
*
* **Type:** `number`
*
* ---
*
* **Details:**
*
* You can enable the revision management if you need to refresh the consent due to a change your cookie/privacy policy.
*
* - The default value `0` means that revision management is disabled.
* - Set any number different from `0` to enable revision management.
*
* ---
*
* **Example:**
*
* To enable revisions, you just need to specify a valid revision number in your configuration.
* Once enabled, users who had already consented to revision 0, will be prompted again for consent.
*
* ```typescript
* CookieConsent.run({
* revision: 1
* });
* ```
*
* ---
*
* **Revision message:**
*
* Optionally, you can also set a revision message to let your users know what has changed since the last time they visited.
*
* 1. Add a `revisionMessage` field inside `consentModal`
* 2. Specify the `{{revisionMessage}}` placeholder inside `consentModal.description`
*
* ```typescript
* CookieConsent.run({
* revision: 1,
* language: {
* // ...
* translations: {
* en: {
* consentModal: {
* description: "Modal description. <br> {{revisionMessage}}",
* revisionMessage: "Hi, we've made some changes to our cookie policy",
* // ...
* },
* // ...
* }
* }
* }
* });
* ```
*/
revision?: number;
/**
* Root element where the modal will be appended.
*
* ---
*
* **Default:** `document.body`
*
* ---
*
* **Type:** `string | HTMLElement`
*
* ---
*
* **Details:**
*
* Root (parent) element where the modal will be appended as a last child.
*
* ---
*
* **Example:**
*
* ```typescript
* CookieConsent.run({
* root: "#app" // CSS selector
* });
* ```
*/
root?: Element | null | string;
}
/**
* Firebase configuration for cookie consent storage
*
* @extends FirebaseOptions
* @property {string} [collectionName] - Optional name of the Firestore collection
*
* @exports {FirebaseConfig}
*/
interface FirebaseConfig extends FirebaseOptions {
/**
* The name of the Firestore collection where cookie consent data will be stored
*
* @description
* Specifies the client web application name (e.g. "Africa Exchange"
* or "BankX") where the cookie consent is being managed, to ensure
* proper data organization and retrieval.
*/
collectionName: string;
}
interface AutoClear {
/**
* Array of cookies to clear.
*
* ---
*
* **Example:**
*
* ```typescript
* cookies: [
* { name: /^_ga/ }, // regex: match all cookies starting with "_ga"
* { name: "_gid" }, // string: exact cookie name
* ]
* ```
*/
cookies: CookieItem[];
/**
* Reload page after the autoClear function.
*
* @default false
*/
reloadPage?: boolean;
}
interface Category {
/**
* Declare the cookies to erase when the user rejects the category.
*/
autoClear?: AutoClear;
/**
* Mark category as enabled by default.
*
* If mode is set to `"opt-out"` and consent has not yet been expressed, the category
* is automatically enabled (and scripts under this category will be executed).
*
* @default false
*/
enabled?: boolean;
/**
* Treat the category as necessary. The user won't be able to disable the category.
*
* @default false
*/
readOnly?: boolean;
/**
* Configure individually togglable services.
*/
services?: {
[key: string]: Service;
};
}
interface ConsentModalOptions {
/**
* Text of the `Accept all` button.
*
* @example
*
* ```typescript
* consentModal: {
* acceptAllBtn: "Accept all"
* }
* ```
*/
acceptAllBtn?: string;
/**
* Text of the `Accept necessary` button.
*
* @example
*
* ```typescript
* consentModal: {
* acceptNecessaryBtn: "Accept necessary"
* }
* ```
*/
acceptNecessaryBtn?: string;
/**
* Specify to generate a big `X` (accept necessary) button. Visible in the `box` layout only.
*
* @example
*
* ```typescript
* consentModal: {
* closeIconLabel: "Accept necessary"
* }
* ```
*/
closeIconLabel?: string;
/**
* Description of the modal.
*
* @example
*
* ```typescript
* consentModal: {
* description: "This website uses cookies to ensure you get the best experience."
* }
* ```
*/
description?: string;
/**
* Custom HTML string where you can put links pointing to your privacy policy.
*
* @example
*
* ```typescript
* consentModal: {
* footer: "<a href="/impressum">Impressum</a> <a href="/privacy-policy">Privacy Policy</a>"
* }
* ```
*/
footer?: string;
/**
* Accessibility label. Especially useful if no title is provided.
*
* @example
*
* ```typescript
* consentModal: {
* label: "Cookie consent"
* }
* ```
*/
label?: string;
/**
* Set a revision message, visible when the revision number changes.
* Check out the [docs](https://cookieconsent.orestbida.com/advanced/revision-management.html) for more.
*
* @example
*
* ```typescript
* consentModal: {
* description: "Modal description. <br> {{revisionMessage}}"
* revisionMessage: "Hi, we've made some changes to our cookie policy since the last time you visited!"
* }
* ```
*/
revisionMessage?: string;
/**
* Text of the `Show preferences` button.
*
* @example
*
* ```typescript
* consentModal: {
* showPreferencesBtn: "Manage individual preferences"
* }
* ```
*/
showPreferencesBtn?: string;
/**
* Title of the modal.
*
* @example
*
* ```typescript
* consentModal: {
* title: "We use cookies!"
* }
* ```
*/
title?: string;
}
interface CookieOptions {
/**
* Current domain/subdomain's name, retrieved automatically.
*
* @default window.location.hostname
*/
domain?: string;
/**
* Number of days before the cookie expires.
*
* ---
*
* **Default:** `182`
*
* ---
*
* **Type:** `number | ((acceptType: string) => number)`
*
* ---
*
* **Details:**
*
* This field also accepts a function that must return a number.
* The acceptType parameter is equal to `getUserPreferences().acceptType`.
*
* ---
*
* **Example:**
*
* If the user accepted all categories, set expiresAfterDays=365.25,
* otherwise set expiresAfterDays=182.
*
* ```typescript
* CookieConsent.run({
* cookie: {
* expiresAfterDays: (acceptType) => {
* return acceptType === "all"
* ? 365.25
* : 182;
* }
* }
* })
* ```
*/
expiresAfterDays?: ((acceptType: AcceptType) => number) | number;
/**
* Cookie name.
*
* @default "__Host-CCID"
*/
name?: string;
/**
* Cookie path.
*
* @default "/"
*/
path?: string;
/**
* Cookie sameSite.
*
* @default "Lax"
*/
sameSite?: "Lax" | "None" | "Strict";
/**
* Toggle the secure flag.
*
* ---
*
* **Default:** `true`
*
* ---
*
* **Type:** `boolean`
*
* ---
*
* **Details:**
*
* The secure flag won't be set if there is no https connection.
*/
secure?: boolean;
/**
* Store the content of the cookie in localstorage
*
* ---
*
* **Default:** `false`
*
* ---
*
* **Type:** `boolean`
*
* ---
*
* **Details:**
*
* When enabled, the following fields are ignored: `domain`, `path`, `sameSite`
*/
useLocalStorage?: boolean;
}
interface CookieTable {
/**
* Define the table body items (rows).
*
* ---
*
* **Example:**
*
* ```typescript
* cookieTable: {
* body: [
* {
* name: "_ga",
* domain: "Google Analytics",
* description: "Cookie set by <a href=\"https://business.safety.google/adscookies/\">Google Analytics</a>",
* expiration: "Expires after 12 days"
* },
* {
* name: "_gid",
* domain: "Google Analytics",
* description: "Cookie set by <a href=\"https://business.safety.google/adscookies/\">Google Analytics</a>",
* expiration: "Session"
* }
* ]
* }
* ```
*/
body: {
[key: string]: string;
}[];
/**
* Table caption
*
* ---
*
* **Example:**
*
* ```typescript
* cookieTable: {
* caption: "List of cookies"
* }
* ```
*/
caption?: string;
/**
* Define the table headers (columns).
*
* ---
*
* **Example:**
*
* ```typescript
* cookieTable: {
* headers: {
* name: "Name",
* domain: "Service",
* description: "Description",
* expiration: "Expiration"
* }
* }
* ```
*/
headers: {
[key: string]: string;
};
}
interface GuiOptions {
consentModal?: {
/**
* Stylize the accept and reject buttons the same way (GDPR compliant).
*
* @default true
*/
equalWeightButtons?: boolean;
/**
* Flip buttons.
*
* @default false
*/
flipButtons?: boolean;
/**
* Change consentModal layout.
*
* @default "box"
*/
layout?: ConsentModalLayout;
/**
* Change modal position.
*
* @default "bottom right"
*/
position?: ConsentModalPosition;
};
preferencesModal?: {
/**
* Stylize the accept and reject buttons the same way (GDPR compliant).
*
* @default true
*/
equalWeightButtons?: boolean;
/**
* Flip buttons.
*
* @default false
*/
flipButtons?: boolean;
/**
* Change preferencesModal layout.
*
* @default "box"
*/
layout?: PreferencesModalLayout;
/**
* This options is valid only if layout=bar.
*
* @default "right"
*/
position?: PreferencesModalPosition;
};
}
interface PreferencesModalOptions {
/**
* Text of the `Accept all` button.
*
* @example
*
* ```typescript
* preferencesModal: {
* acceptAllBtn: "Accept all"
* }
* ```
*/
acceptAllBtn?: string;
/**
* Text of the `Reject all` button.
*
* @example
*
* ```typescript
* preferencesModal: {
* acceptNecessaryBtn: "Reject all"
* }
* ```
*/
acceptNecessaryBtn?: string;
/**
* Accessibility label.
*
* @example
*
* ```typescript
* preferencesModal: {
* closeIconLabel: "Close modal"
* }
* ```
*/
closeIconLabel?: string;
/**
* Text of the `Accept current selection` button.
*
* @example
*
* ```typescript
* preferencesModal: {
* savePreferencesBtn: "Accept current selection"
* }
* ```
*/
savePreferencesBtn?: string;
/**
* Sections to display in the preferences modal.
* Each section can have a title, description, linked category, and a cookie table.
*
* ---
*
* **Type:**
*
* ```typescript
* interface Section {
* title?: string
* description?: string
* linkedCategory?: string
* cookieTable?: CookieTable
* }
* ```
*
* ---
*
* **Details:**
*
* - `linkedCategory`: by specifying the name of a defined category (e.g. "analytics"), a toggle will be generated
* - `cookieTable`: html table where you can list and clarify the cookies under this category
*
* ---
*
* **Basic usage:**
*
* ```ts
* preferencesModal: {
* [
* {
* title: 'Somebody said ... cookies?',
* description: 'I want one!'
* },
* {
* title: 'Strictly Necessary cookies',
* description: 'These cookies are essential for the proper functioning of the website and cannot be disabled.',
*
* // this field will generate a toggle linked to the 'necessary' category
* linkedCategory: 'necessary'
* },
* ]
* }
* ```
*
* ---
*
* **Comprehensive Example:**
*
* ```typescript
* preferencesModal: {
* sections: [
* {
* title: "Strictly Necessary cookies",
* description: "These cookies are essential for the proper functioning of the website and cannot be disabled.",
* linkedCategory: "necessary"
* },
* {
* title: "Performance and Analytics",
* description: "These cookies collect information about how you use our website.",
* linkedCategory: "analytics",
* cookieTable: {
* caption: "List of cookies",
* headers: {
* name: "Name",
* description: "Description",
* duration: "Duration"
* },
* body: [
* {
* name: "cookie_name",
* description: "Cookie description",
* duration: "1 year"
* },
* ]
* }
* },
* ]
* }
* ```
*/
sections: Section[];
/**
* Label to append to services counter.
*
* if you're using services, you can specify a label such as `"Service(s)"` to clarify what the counter means.
* The counter will not be displayed if `guiOptions.preferencesModal.layout` is set to `bar`, as well as on narrow viewports.
*
* @example
*
* ```typescript
* preferencesModal: {
* serviceCounterLabel: "services"
* }
* ```
*/
serviceCounterLabel?: string;
/**
* Title of the modal.
*
* @example
*
* ```typescript
* preferencesModal: {
* title: "Manage cookie preferences"
* }
* ```
*/
title?: string;
}
interface Section {
/**
* Create a custom html table (generally used to clarify cookies).
*
* ---
*
* **Type:**
*
* ```typescript
* interface CookieTable {
* caption?: string
* headers: {[key: string]: string}
* body: {[key: string]: string}[]
* }
* ```
*
* ---
*
* **Example:**
*
* ```typescript
* cookieTable: {
* caption: "List of cookies",
* headers: {
* name: "Name",
* description: "Description",
* duration: "Duration"
* },
* body: [
* {
* name: "cookie-name",
* description: "cookie-description",
* duration: "cookie-duration"
* },
* {
* name: "cookie-name-2",
* description: "cookie-description-2",
* duration: "cookie-duration-2"
* }
* ]
* }
* ```
*/
cookieTable?: CookieTable;
/**
* Section description.
*/
description?: string;
/**
* Name of a valid category. This will convert the current section into a "togglable" category.
* By specifying the name of a defined category (e.g. "analytics"), a toggle will be generated.
*
* ---
*
* **Example:**
*
* ```typescript
* preferencesModal: {
* sections: [
* {
* title: "Performance and Analytics",
* description: "These cookies collect information about how you use our website.",
* linkedCategory: "analytics"
* }
* ]
* }
* ```
*/
linkedCategory?: string;
/**
* Section title.
*/
title?: string;
}
interface Translation {
/**
* All the options/fields also allow html markup.
*
* **Type:**
*
* ```typescript
* interface ConsentModal {
* label?: string
* title?: string
* description?: string
* acceptAllBtn?: string
* acceptNecessaryBtn?: string
* showPreferencesBtn?: string
* closeIconLabel?: string
* revisionMessage?: string
* footer?: string
* }
* ```
*
* ---
*
* **Details:**
*
* All the `options/fields` also allow html markup.
*
* - `closeIconLabel`: if specified, a big `X` button will be generated (visible only in the box layout). It acts the same as `acceptNecessaryBtn`.
* - `revisionMessage`: check out the dedicated [revision](https://cookieconsent.orestbida.com/advanced/revision-management.html#revision-message) section.
* - `footer`: a small area where you can place your links (impressum, privacy policy, ...)
*
* ---
*
* **Example:**
*
* ```typescript
* translations: {
* "en": {
* consentModal: {
* label: "Cookie Preferences Center",
* title: "We use cookies!",
* description: "This website uses cookies to ensure you get the best experience on our website.",
* acceptAllBtn: "Accept all",
* acceptNecessaryBtn: "Accept necessary",
* showPreferencesBtn: "Manage individual preferences",
* footer: `
* <a href="#path-to-impressum.html" target="_blank">Impressum</a>
* <a href="#path-to-privacy-policy.html" target="_blank">Privacy Policy</a>
* `
* }
* }
* }
* ```
*/
consentModal: ConsentModalOptions;
/**
* You can define any table, with the headers you deem more fit.
*
* ---
*
* * **Type:**
*
* ```typescript
* interface PreferencesModal {
* title?: string
* acceptAllBtn?: string
* acceptNecessaryBtn?: string
* savePreferencesBtn?: string
* closeIconLabel?: string
* serviceCounterLabel?: string
* sections: Section[]
* }
* ```
*
* ---
*
* **Details:**
*
* - `serviceCounterLabel`: if you're using services, you can specify a label such as `"Service(s)"` to clarify what the counter means.
* The counter will not be displayed if `guiOptions.preferencesModal.layout` is set to `bar`, as well as on narrow viewports.
*
* ---
*
* **Example:**
*
* ```typescript
* {
* title: "Manage cookie preferences",
* acceptAllBtn: "Accept all",
* acceptNecessaryBtn: "Reject all",
* savePreferencesBtn: "Accept current selection",
* closeIconLabel: "Close modal",
* sections: [
* {
* title: "Strictly Necessary cookies",
* description: "These cookies are essential for the proper functioning of the website and cannot be disabled.",
* linkedCategory: "necessary"
* },
* ]
* }
* ```
*/
preferencesModal: PreferencesModalOptions;
}
type DeepPartial<Argument> = Argument extends Record<PropertyKey, unknown> ? {
[Key in keyof Argument]?: DeepPartial<Argument[Key]>;
} : Partial<Argument>;
declare function createCookieConfiguration(options?: DeepPartial<CookieConsentConfiguration>): CookieConsentConfiguration;
type CookieConsentModal = {
[K in ConsentModal]?: CSSObject;
};
type ConsentModal = ConsentModalBlock | ConsentModalBlockElements | ConsentModalBlockElementsModifiers | ConsentModalBlockModifiers;
type ConsentModalBlock = ".cm-wrapper";
type ConsentModalBlockElements = ".cm__body" | ".cm__btn" | ".cm__btn-group" | ".cm__btns" | ".cm__close" | ".cm__desc" | ".cm__footer" | ".cm__link-group" | ".cm__links" | ".cm__texts" | ".cm__title";
type ConsentModalBlockElementsModifiers = ".cm__btn--close" | ".cm__btn--secondary" | ".cm__btn-group--uneven";
type ConsentModalBlockModifiers = ".cm--bar" | ".cm--bottom" | ".cm--box" | ".cm--center" | ".cm--cloud" | ".cm--flip" | ".cm--inline" | ".cm--left" | ".cm--middle" | ".cm--right" | ".cm--top" | ".cm--wide";
type CookieModal = {
[Key in Modal | Theme]?: CSSInterpolation;
};
type Modal = "#cc-main";
type Theme = ".cc--darkmode" | ".default-light";
type CookieVariable = BackgroundVariable | CategoryVariable | ColorVariable | FooterVariable | GeneralVariable | ModalVariable | PrimaryButtonVariable | ScrollbarVariable | SecondaryButtonVariable | ToggleVariable;
type CookieVariables = {
[K in CookieVariable]?: number | string;
};
type BackgroundVariable = "--cc-bg" | "--cc-overlay-bg";
type CategoryVariable = "--cc-cookie-category-block-bg" | "--cc-cookie-category-block-border" | "--cc-cookie-category-block-hover-bg" | "--cc-cookie-category-block-hover-border" | "--cc-cookie-category-expanded-block-bg" | "--cc-cookie-category-expanded-block-hover-bg" | "--cc-section-category-border";
type ColorVariable = "--cc-link-color" | "--cc-primary-color" | "--cc-secondary-color" | "--cc-separator-border-color";
type FooterVariable = "--cc-footer-bg" | "--cc-footer-border-color" | "--cc-footer-color";
type GeneralVariable = "--cc-font-family" | "--cc-z-index";
type ModalVariable = "--cc-modal-border-radius" | "--cc-modal-margin" | "--cc-modal-transition-duration";
type PrimaryButtonVariable = "--cc-btn-border-radius" | "--cc-btn-primary-bg" | "--cc-btn-primary-border-color" | "--cc-btn-primary-color" | "--cc-btn-primary-hover-bg" | "--cc-btn-primary-hover-border-color" | "--cc-btn-primary-hover-color";
type ScrollbarVariable = "--cc-webkit-scrollbar-bg" | "--cc-webkit-scrollbar-hover-bg";
type SecondaryButtonVariable = "--cc-btn-secondary-bg" | "--cc-btn-secondary-border-color" | "--cc-btn-secondary-color" | "--cc-btn-secondary-hover-bg" | "--cc-btn-secondary-hover-border-color" | "--cc-btn-secondary-hover-color";
type ToggleVariable = "--cc-pm-toggle-border-radius" | "--cc-toggle-disabled-icon-color" | "--cc-toggle-enabled-icon-color" | "--cc-toggle-off-bg" | "--cc-toggle-off-knob-bg" | "--cc-toggle-on-bg" | "--cc-toggle-on-knob-bg" | "--cc-toggle-readonly-bg" | "--cc-toggle-readonly-knob-bg" | "--cc-toggle-readonly-knob-icon-color";
type CookiePreferencesModal = {
[K in PreferencesModal]?: CSSObject;
};
type PreferencesModal = PreferencesModalBlock | PreferencesModalBlockElements | PreferencesModalBlockElementsModifiers | PreferencesModalBlockModifiers;
type PreferencesModalBlock = ".pm-overlay" | ".pm-wrapper";
type PreferencesModalBlockElements = ".pm__badge" | ".pm__body" | ".pm__btn" | ".pm__btn-group" | ".pm__close-btn" | ".pm__footer" | ".pm__header" | ".pm__section" | ".pm__section-arrow" | ".pm__section-desc" | ".pm__section-desc-wrapper" | ".pm__section-services" | ".pm__section-table" | ".pm__section-title" | ".pm__section-title-wrapper" | ".pm__section-toggles" | ".pm__service" | ".pm__service-counter" | ".pm__service-header" | ".pm__service-icon" | ".pm__service-title" | ".pm__table-caption" | ".pm__table-head" | ".pm__table-td" | ".pm__table-th" | ".pm__table-tr" | ".pm__title";
type PreferencesModalBlockElementsModifiers = ".pm__btn--secondary" | ".pm__section--expandable" | ".pm__section--toggle";
type PreferencesModalBlockModifiers = ".pm--bar" | ".pm--box" | ".pm--flip" | ".pm--left" | ".pm--right" | ".pm--wide";
interface ArrayCSSInterpolation extends ReadonlyArray<CSSInterpolation> {
}
type CookieStyles = CSSObject;
type CSSInterpolation = ArrayCSSInterpolation | InterpolationPrimitive;
interface CSSObject extends CookieConsentModal, CookieModal, CookiePreferencesModal, CookieVariables, CSSOthersObject, CSSPropertiesWithMultiValues, CSSPseudos {
}
interface CSSOthersObject {
[propertiesName: string]: CSSInterpolation;
}
type CSSPseudos = {
[K in Pseudos]?: CSSObject;
};
type InterpolationPrimitive = boolean | CSSObject | Keyframes | null | number | string | undefined;
declare function createCookieStyles(styles: CookieStyles): CSSObject;
/**
* Returns a CSS variable as a string.
*
* @param variable - The CSS variable to return.
* @returns The CSS variable as a string.
*
* @example
*
* ```typescript
* import { css } from 'cookies';
*
* const primaryColor = css('--cc-primary-color');
* console.log(primaryColor); // Outputs: var(--cc-primary-color)
* ```
*
* @see {@link CookieVariable} for a list of available CSS variables.
* @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/var() var()} for more information on CSS variables.
*/
declare function css(variable: CookieVariable | (string & {})): string;
type CookieBannerAppearance = {
/**
* The active theme, defaults to "light"
*
* @default "light"
*
* @example
*
* ```ts
* const activeTheme = "dark";
* ```
*/
activeTheme?: "dark" | "light";
/**
* The styles to be applied to the cookie banner. This is an object where the keys are the variant names and the values are the styles.
* The styles are defined using CSS properties and can include nested selectors.
*
* @example
*
* ```ts
* {
* ".cc--darkmode": {
* "&:hover :not(.default-light)": {
* "--cc-bg": "green",
* },
* },
* }
* ```
*/
styles?: CookieStyles;
};
/**
* Props for the CookieBanner compo