Configuration Reference

Overview of all the available configuration options.

About the examples

All the examples in this section are partial code snippets. They do not represent full/valid configurations.

root

Root (parent) element where the modal will be appended as a last child.

• Type: string | HTMLElement
• Default: document.body
• Example:
  

  CookieConsent.run({
      root: '#app'  // css selector
  })

mode

Changes the scripts' activation logic when consent is not valid.

• Type: string

• Values: 'opt-in', 'opt-out'

• Default: 'opt-in'

• 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):

  const euCountries = ['DE', 'FR', 'IT',  ...];
  const userCountry = "IT";
  
  const dynamicMode = euCountries.contains(userCountry) ? 'opt-in' : 'opt-out';
  
  CookieConsent.run({
      mode: dynamicMode
  })

autoShow

Automatically show the consent modal if consent is not valid.

• Type: boolean

• Default: true

• Example:

  Disable autoShow and show modal after 3 seconds:

  CookieConsent.run({
      autoShow: false
  })
  
  setTimeout(CookieConsent.show, 3000)

revision

Manages consent revisions; useful if you'd like to ask your users again for consent after a change in your cookie/privacy policy.

• Type: number

• Default: 0

• Details:

  The default value 0 means that revision management is disabled. You can set any number different from 0 in order to enable it. Check out the dedicated revision management section.

manageScriptTags

Intercepts all <script> tags with a data-category attribute, and enables them based on the accepted categories. Check out the scripts management section for details and examples.

• Type: boolean
• Default: true

autoClearCookies

Clears cookies when user rejects a specific category. It requires a valid autoClear array.

• Type: boolean

• Default: true

• 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

hideFromBots

Stops the plugin's execution when a bot/crawler is detected, to prevent them from indexing the modal's content.

• Type: boolean
• Default: true

disablePageInteraction

Creates a dark overlay and blocks the page scroll until consent is expressed.

• Type: boolean
• Default: false

lazyHtmlGeneration

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.

• Type: boolean
• Default: true

cookie

Customize the plugin's cookie.

• Type:

  interface Cookie {
      name?: string,
      domain?: string,
      path?: string,
      expiresAfterDays?: number | (acceptType: string) => number,
      sameSite?: string,
      useLocalStorage?: boolean
  }

• Default:

  {
      name: 'cc_cookie',
      domain: window.location.hostname,
      path: '/',
      expiresAfterDays: 182,
      sameSite: 'Lax',
      useLocalStorage: false
  }

INFO

The cookie is automatically set with the secure flag if https is detected.

cookie.name

• Type: string
• Default: 'cc_cookie'

cookie.domain

Current domain/subdomain's name, retrieved automatically.

• Type: string
• Default: window.location.hostname

cookie.path

• Type: string
• Default: '/'

cookie.expiresAfterDays

Number of days before the cookie expires.

• Type:

  number | (acceptType: string) => number

• Default: 182

• 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.

  CookieConsent.run({
      cookie: {
          expiresAfterDays: acceptType => {
              return acceptType === 'all'
                  ? 365.25
                  : 182;
          }
      }
  })

cookie.sameSite

• Type: string
• Values: 'Lax', 'Strict', 'None'
• Default: 'Lax'

cookie.useLocalStorage

Store the value of the cookie in localStorage.

• Type: boolean

• Default: false

• Details:

  When enabled, the following fields are ignored: domain, path, sameSite

onFirstConsent

Callback function executed once, on the user's first consent action.

• Type:

  function({
      cookie: {} // same as CookieConsent.getCookie()
  }): void

• Example:
  

  CookieConsent.run({
      onFirstConsent: ({cookie}) => {
          // do something
      }
  })

INFO

This callback function is also executed on revision change.

onConsent

Callback function executed on the user's first consent action and after each page load.

• Type:

  function({
      cookie: {} // same value as CookieConsent.getCookie()
  }): void

• Example:
  

  CookieConsent.run({
      onConsent: ({cookie}) => {
          // do something
      }
  })

INFO

This callback function is also executed on revision change.

onChange

Callback function executed when the user's preferences — such as accepted categories and services — change.

• Type:

  function({
      cookie: {},   // same as CookieConsent.getCookie()
      changedCategories: string[],
      changedPreferences: {[category: string]: string[]}
  }): void

• Example:
  

  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
                  }
              }
          }
      }
  })

onModalShow

Callback function executed when one of the modals is visible.

• Type:

  function({
      modalName: string
  }): void

• Example:
  

  CookieConsent.run({
      onModalShow: ({modalName}) => {
          // do something
      }
  })

• Details:

  modalName equals to one of the following values:

  • 'consentModal'
  • 'preferencesModal'

onModalHide

Callback function executed when one of the modals is hidden.

• Type:

  function({
      modalName: string
  }): void

• Example:
  

  CookieConsent.run({
      onModalHide: ({modalName}) => {
          // do something
      }
  })

• Details:

  modalName equals to one of the following values:

  • 'consentModal'
  • 'preferencesModal'

onModalReady

Callback function executed when one of the modals is created and appended to the DOM.

• Type:

  function({
      modalName: string
  }): void

• Example:
  

  CookieConsent.run({
      onModalReady: ({modalName, modal}) => {
          // do something
      }
  })

• Details:

  modalName equals to one of the following values:

  • 'consentModal'
  • 'preferencesModal'

guiOptions

Tweak main UI settings.

• Type:

  interface GuiOptions {
      consentModal?: ConsentModalOptions
      preferencesModal?: PreferencesModalOptions
  }

guiOptions.consentModal

• Type:

  interface ConsentModalOptions {
      layout?: string
      position?: string
      flipButtons?: boolean
      equalWeightButtons?: boolean
  }

• Default:

  {
      layout: 'box',
      position: 'bottom right',
      flipButtons: false,
      equalWeightButtons: true
  }

• Details:

  All available layout and position options.

  Layout	Variant(s)	Position-Y	Position-X
  box	wide, inline	top, middle, bottom	left, center, right
  cloud	inline	top, middle, bottom	left, center, right
  bar	inline	bottom	-

  Note

  Valid layout syntax: <layoutName> <layoutVariant>.
  Valid position syntax: <positionY> <positionX>.

• Example:

  guiOptions: {
      consentModal: {
          layout: 'cloud inline',
          position: 'bottom center'
      }
  }

guiOptions.preferencesModal

• Type:

  interface PreferencesModalOptions {
      layout?: string
      position?: string
      flipButtons?: boolean
      equalWeightButtons?: boolean
  }

• Default:

  {
      layout: 'box',
      position: 'right',
      flipButtons: false,
      equalWeightButtons: true
  }

• Details:

  All available layout and position options.

  Layout	Variant(s)	Position-Y	Position-X
  box	-	-	-
  bar	wide	-	left, right

  Note

  Valid layout syntax: <layoutName> <layoutVariant>.
  Valid position syntax: <positionX> (if any available).

• Example:

  guiOptions: {
      preferencesModal: {
          layout: 'bar wide',
          position: 'left',
          equalWeightButtons: false,
          flipButtons: true
      }
  }

categories

Use to define your cookie categories.

• Type:

  {[category: string]: {
      enabled?: boolean,
      readOnly?: boolean,
      autoClear?: AutoClear,
      services?: Service[]
  }}

• Example:

  How to define the analytics category:

  CookieConsent.run({
      categories: {
          analytics: {}
      }
  })

[category].enabled

Mark the category as enabled by default.

• Type: boolean
• Default: false
• Example:
  

  CookieConsent.run({
      categories: {
          necessary: {
              enabled: true
          },
          analytics: {
              enabled: false
          }
      }
  })

[category].readOnly

Treat the category as read-only/necessary (always enabled).

• Type: boolean
• Default: false
• Example:

  CookieConsent.run({
      categories: {
          necessary: {
              readOnly: true
          }
      }
  })

[category].autoClear

Clear cookies when the user rejects the cookie category.

• Type:

  interface AutoClear {
      cookies: Cookie[]
      reloadPage: boolean
  }

• Details:

  • autoClear.cookies: Cookie[] array of Cookie objects
  • autoClear.reloadPage: boolean reload page on clear

  Cookie type:

  {
      name: string | RegExp
      path?: string
      domain?: string
  }

• Example:
  

  Clear the '_gid' cookie and all the other cookies starting with '_ga' when the user opts-out of the "analytics" category.

  CookieConsent.run({
      categories: {
          analytics: {
              readOnly: false,
              autoClear: {
                  cookies: [
                      {
                          name: /^(_ga)/      //regex
                      },
                      {
                          name: '_gid'        //string
                      }
                  ]
              }
          }
      }
  })

WARNING

If you've installed CookieConsent in a subdomain, and the cookie you're trying to erase is in the main domain, you'll have to specify your main domain in the domain field of the Cookie object.

[category].services

Define individually togglable services.

• Type:

  {
      [service: string]: {
          label?: string
          onAccept?: () => void
          onReject?: () => void
          cookies?: CookieItem[]
      }
  }

• Details:

  • label: overwrites the visible name in the preferencesModal (can be html)
  • onAccept: callback function executed when the service is accepted
  • onReject: callback function executed when the service is rejected (assuming that it was previously accepted)
  • cookies: array of cookies to erase when the service is disabled/rejected

• Example:

  Defining 2 services: ga and new_service:

  CookieConsent.run({
      categories: {
          analytics: {
              services: {
                  ga: {
                      label: 'Google Analytics',
                      onAccept: () => {
                          // enable ga
                      },
                      onReject: () => {
                          // disable ga
                      },
                      cookies: [
                          {
                              name: /^(_ga|_gid)/
                          }
                      ]
                  },
                  new_service: {
                      label: 'Another Service',
                      onAccept: () => {
                          // enable new_service
                      },
                      onReject: () => {
                          // disable new_service
                      }
                  }
              }
          }
      }
  })

INFO

If one or more services are enabled, then the entire category will be treated as enabled/accepted.

language

Define your language settings and the translation(s).

• Type:

  interface Language {
      default: string
      autoDetect?: string
      rtl?: string | string[]
      translations: {
          [locale: string]:
              Translation
              | string
              | (() => Translation)
              | (() => Promise<Translation>)
      }
  }

language.default

The desired default language.

• Type: string
• Example:

  CookieConsent.run({
      language: {
          default: 'en'
      }
  })

language.autoDetect

Set the current language dynamically.

• Type: string

• Values: 'document', 'browser'

• Details:
  

  • 'document': retrieve language from the lang attribute (e.g. <html lang="en-US">)
  • 'browser': retrieve the user's browser language via navigator.language

  INFO

  The detected language will be used only if a valid translation is defined, otherwise the plugin will fallback to the default language.

language.rtl

List of languages that should use the RTL layout.

• Type: string | string[]
• Example:
  

  CookieConsent.run({
      language: {
          default: 'en',
          rtl: 'ar',  // enable RTL for Arabic
          autoDetect: 'browser',
  
          translations: {
              en: '/assets/translations/en.json',
              ar: '/assets/translations/ar.json'
          }
      }
  })

language.translations

Define the translation(s) content.

• Type:

  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:

  CookieConsent.run({
      language: {
          default: 'en',
          translations: {
              en: '/assets/translations/en.json'
          }
      }
  })

  Inline translation object:

  CookieConsent.run({
      language: {
          default: 'en',
          translations: {
              en: {
                  consentModal: {
                      // ...
                  },
                  preferencesModal: {
                      // ...
                  }
              }
          }
      }
  })

  You can also fetch a translation asynchronously:

  CookieConsent.run({
      language: {
          default: 'en',
          translations: {
              en: async () => {
                  const res = fetch('path-to-json-translation');
                  return await res.json();
              }
          }
      }
  })

[translation].consentModal

• Type:

  interface ConsentModal {
      label?: string
      title?: string
      description?: string
      acceptAllBtn?: string
      acceptNecessaryBtn?: string
      showPreferencesBtn?: string
      closeIconLabel?: string
      revisionMessage?: string
      footer?: string
  }

• Details:

  • 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 section.
  • footer: a small area where you can place your links (impressum, privacy policy ...)
  
  

  INFO

  All the options/fields also allow html markup.

• Example:

  translations: {
      'en': {
          consentModal: {
              label: 'Cookie Consent',
              title: 'We use cookies!',
              description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua',
              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>
              `
          }
      }
  }

[translation].preferencesModal

• Type:

  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:

  translations: {
      'en': {
          preferencesModal: {
              title: 'Cookie Preferences Center',
              acceptAllBtn: 'Accept all',
              acceptNecessaryBtn: 'Accept necessary only',
              savePreferencesBtn: 'Accept current selection',
              closeIconLabel: 'Close modal',
              sections: []
          }
      }
  }

[translation].preferencesModal.sections

• Type:

  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

  CookieTable type:

  interface CookieTable {
      caption?: string
      headers: {[key: string]: string}
      body: {[key: string]: string}[]
  }

• Example:

  sections: [
      {
          title: 'Section name',
          description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua'
      },
      {
          title: 'Section name',
          description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua',
          linkedCategory: 'necessary'
      },
      {
          title: 'Analytics Cookies',
          description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua',
          linkedCategory: 'analytics',
          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'
                  }
              ]
          }
      }
  ]

  TIP

  You can define any table, with the headers you deem more fit.