JavaScript API

How to use the Cookie Consent JavaScript API

You can add additional options to the code snippet.

Javascript and CSS can be included from the CDN or hosted on your own site. Download source from GitHub.


This example places an informational (default) red and white Cookie Consent popup inside the content block of a website (instead of body).

It disables the regional law options and shows revoke option for everyone. A callback hook is used to enable or disable cookies when the consent changes. <head> <link rel="stylesheet" type="text/css" href="css/cookieconsent.min.css" /> </head> <body> <script src="js/cookieconsent.min.js"></script> <script> window.cookieconsent.initialise({ container: document.getElementById("content"), palette:{ popup: {background: "#fff"}, button: {background: "#aa0000"}, }, revokable:true, onStatusChange: function(status) { console.log(this.hasConsented() ? 'enable cookies' : 'disable cookies'); }, law: { regionalLaw: false, }, location: true, }); </script> </body>

Static configuration

cookieconsent.status (object)
Default: {deny: ‘deny’, allow: ‘allow’, dismiss: ‘dismiss’}

These are the possible values that the cookie can be set to.

cookieconsent.hasTransition (boolean)
Default: true (if transitions are supported by the browser)

Animations are set to true by default in cookie consent. This includes the fade in/out and slide up/down animations. Set this to false to disable all animations.

Main options

These are the main options that can be passed to the Cookie Consent tool.

enabled (boolean)
Default: true

This can be used to disable the popup. It is internally used to disable itself (if needed), but can be configured externally too.

container (HTMLElement)
Default: null

The tool is automatically appended to the HTML body. Use this option to select the parent element. Use autoOpen: false to prevent the tool automatically appending itself to any container.

It is recommended to set these values to correspond with your server. You MUST set the ‘domain’ option, otherwise your cookies may not work. (string)
Default: ‘cookieconsent_status’

Name of the cookie that keeps track of users choice

cookie.path (string)
Default: ‘/’

URL path that the cookie ‘name’ belongs to. The cookie can only be read at this location

cookie.domain (string)
Default: ”

The domain that the cookie ‘name’ belongs to. The cookie can only be read on this domain. Guide to cookie domains

cookie.expiryDays (integer)
Default: 365

The cookies expire date, specified in days (specify -1 for no expiry) (boolean)
Default: false

If secure is true, the cookies will only be allowed over https

Content options

Text strings used for cookie consent window elements.

content (object)
content: { header: 'Cookies used on the website!', message: 'This website uses cookies to improve your experience.', dismiss: 'Got it!', allow: 'Allow cookies', deny: 'Decline', link: 'Learn more', href: '', close: '&#x274c;', policy: 'Cookie Policy', target: '_blank', }

Overwrite these default options to change the content within the tool

Custom HTML options

elements (object)
elements: { header: '<span class="cc-header"></span>', message: '<span id="cookieconsent:desc" class="cc-message"></span>', messagelink: '<span id="cookieconsent:desc" class="cc-message"> <a aria-label="learn more about cookies" tabindex="0" class="cc-link" href="" target="_blank"></a></span>', dismiss: '<a aria-label="dismiss cookie message" tabindex="0" class="cc-btn cc-dismiss"></a>', allow: '<a aria-label="allow cookies" tabindex="0" class="cc-btn cc-allow"></a>', deny: '<a aria-label="deny cookies" tabindex="0" class="cc-btn cc-deny"></a>', link: '<a aria-label="learn more about cookies" tabindex="0" class="cc-link" href="" target="_blank"></a>', close: '<span aria-label="dismiss cookie message" tabindex="0" class="cc-close"></span>', }

This is the HTML for the elements above. Any word surrounded by ‘’ will be automatically replaced. The string will be replaced with the equivalent text above.
You can remove “” and write the content directly inside the HTML if you want.

ARIA rules suggest to ensure controls are tabable (so the browser can find the first control), and to set the focus to the first interactive control. Learn more about using Aria HTML elements.

window (string)
Default: <div role=”dialog” aria-label=”cookieconsent” aria-describedby=”cookieconsent:desc” class=”cc-window ”></div>

Window is the ‘container’ that houses the popup contents. It has the HTML class ‘cc-window’ and is used for the main positioning of the tool. The placeholders and both get replaced during initialisation.

Layout options

How the content window is built.

The cookie consent tool is built with two main display elements. The message, and the buttons. In this tool, the buttons are grouped into what we call a ‘compliance level’. If you want an ‘opt-in’ level of compliance, then you have two buttons where the default choice is ‘cookies are disable by default’. There are other levels of compliance too. The ones we have by default are stored in the ‘compliance’ option. You can see that the only difference between the compliance levels are the buttons which are used, and how cookies are handled by default

compliance (object)
compliance: { 'info': '<div class="cc-compliance"></div>', 'opt-in': '<div class="cc-compliance cc-highlight"></div>', 'opt-out': '<div class="cc-compliance cc-highlight"></div>', }

Each compliance level contains the HTML needed to render that level of compliance. The ‘cc-compliance’ class is used in the CSS to reference the group of buttons

type (string)
Default: info

The compliance type, which refers to the compliance above. The standard cookie consent popup is purely informational.

layouts (object)
layouts: { 'basic': '', 'basic-close': '', 'basic-header': '', }

Just like the ‘compliance’ buttons are built using the ‘’ markers, the main layout can be built too like this too. The word between these two markers tell the tool what each element is called.

Example: cookieconsent.initialise({ layout: 'my-cool-layout', layouts: { 'my-cool-layout': '<div class="my-cool-layout">\ </div>', }, elements: { pictureOfCat: '<img href="http://placekitten/300/300" />', }, content: { header: 'My awesome cat popup!' } });

layout (string)
Default: basic

The layout type refers to how the tool is rendered. See layouts above.

Position and Theme options

position (string)
Default: bottom

Position is used to describe where on the screen your popup should display. We also use ‘position’ to assume the shape of your popup. If you specify ‘top’ or ‘bottom’, we assume that a full width ‘banner’ is required. If however you specify a horizontal direction, we assume that a corner popup is required (which we call ‘floating’).

We add CSS classes ‘cc-banner’ if the popup displays as a banner, and ‘cc-floating’ if the popup displays as a floating window.

  • top, bottom – Banner
  • top-left, top-right, bottom-left, bottom-right – Floating

theme (string)
Default: block

Cookie Consent is themed, so users can create their own themes. The chosen theme is added to the popup container as a CSS class in the form of .cc-style-THEME_NAME. Available styles:

  • block (default)
  • edgeless
  • classic

Palette options

Colours can be defined in additional stylesheets or using attributes.

palette (object)
Default: null

If palette is set to null, colours have to be defined in CSS.

To pass the colours using attributes, use:
palette: { popup: {background: '#000000', text: '#fff', link: '#fff'}, button: {background: 'transparent', border: '#f8e71c', text: '#f8e71c'}, highlight: {background: '#f8e71c', border: '#f8e71c', text: '#000000'}, }

Highlight is optional and extends `button`. if it exists, it will apply to the rightmost button.
Only background needs to be defined for every element. If text or border colour is not set, it will be calculated from the background colour.

Revoke options

Some countries require consent to be revokable. Cookie Consent keeps track of these countries and adds a button to review the consent window.

revokable (boolean)
Default: false

If set true, revoke button is displayed every time. If false, revoke button is only displayed for advanced compliance options (opt-in and opt-out) and in countries that require revokable consent. The latter can be disabled by _regionalLaw _below.

revokeBtn (string)
Default: <div class=”cc-revoke ”>Cookie Policy</div>

This is the html for the revoke button. This only shows up after the user has selected their level of consent.

animateRevokable (boolean) 
Default: true

If true, the revocable button will translate in and out. Disabled by default for mobile devices.

Behaviour options

showLink (boolean)
Default: true

Used to disable link on existing layouts. If false, replaces element messagelink with message and removes content of link.

static (boolean)
Default: false

The popup uses position fixed to stay in one place on the screen despite any scroll bars. This option makes the popup position static so it displays at the top of the page. A height animation has also been added by default so the popup doesn’t make the page jump, but gradually grows and fades in.

dismissOnScroll (false | integer) 
Default: false

To disable, set to “false”. To enable, set to the number of pixels a user must scroll vertically in order to trigger the dismiss.

dismissOnTimeout (boolean | integer) 
Default: false

Set value as time in milliseconds to autodismiss after set time.

dismissOnWindowClick (boolean) 
Default: false

Set value as true to automatically consent when the user clicks anywhere.

ignoreClicksFrom (array of strings) 
Default: [‘cc-revoke’, ‘cc-btn’]

An array of class names only used with `dismissOnWindowClick`. Add a class name here to ignore clicks from that element.

autoOpen (boolean)
Default: true

This automatically opens the popup if the user hasn’t made a decision yet.

autoAttach (boolean)
Default: true

The tools HTML is automatically appended to the container by default. If you set this to false, you must attach it yourself:
var instance = new cookieconsent.Popup(options); document.body.appendChild(instance.element);

whitelistPage (array) Default: []
blacklistPage (array) Default: []

If set, cookie consent will not be displayed pages defined here. Specify pages using string or RegExp.

  • using a string : ‘/index.html’ (matches ‘/index.html’ exactly)
  • using RegExp : /\/page_[\d]+.html/ (matched ‘/page_1.html’ and ‘/page_2.html’ etc)

overrideHTML (string)
Default: null

If this is defined, then it is used as the inner html instead of layout. This allows for ultimate customisation.
Be sure to use the classes `cc-btn` and `cc-allow`, `cc-deny` or `cc-dismiss`. They enable the app to register click handlers. You can use other pre-existing classes too.

Callback hooks

Called at certain points in the program execution

onPopupOpen: function() {}
This is called when the popup is opened. It can be used to trigger an animation, or to attach extra handlers, etc.

onPopupClose: function() {}
This is called when the popup is closed. It can be used to clean up commands from onPopupOpen

onInitialise: function(status) {}
This is called on start up, with the current chosen compliance. It can be used to tell you if the user has already consented or not as soon as you initialise the tool.

onStatusChange: function(status, chosenBefore) {}
This is called any time the status is changed. This can be used to react to changes that are made to the compliance level. You can use the popup instance functions from within these callbacks too. I.E. ‘this.hasAnswered()’ and ‘this.hasConsented()’.

onRevokeChoice: function() {}
This is called when the user clicks the ‘revoke’ button. This means that their current choice has been invalidated.

Hooks can be used to disable cookies when consent is not given, and the generally extend the tool.

Location options

The location services are disabled by default. You are encouraged to implement a handler to your own service, rather than using the free ones provided.

To enable the basic location services, set ‘location’ to ‘true’. To add you own services or configure the order or execution, pass an object with configuration properties.

location.timeout (array)
Default: 5000 (milliseconds)

We can’t react to errors from script tag resources, so we set a timeout. If we don’t have the answer after 5000ms, try the next service. (array)
Default: [‘ipinfo’]

This array defines the services that you want to use. We attempt to get the country code from the first service, and only if the service fails do we move onto the next service. If all services fail, the popup is opened without modification.

If a service succeeds, then the two letter country code is passed to the ‘Law’ module, with changes your popup options depending on the cookie laws in the country code.

location.serviceDefinitions (object)

This can be used to define new services via a key, but new services they can also go straight into the ‘services’ array in an ad-hoc fashion. It is recommended that you define services in ‘serviceDefinitions’ and use ‘services’ to configure priority between services

Law options

law.countryCode (boolean)
Default: null

Rather than getting the country code from the location services, you can hard code a particular country into the tool.

law.regionalLaw (boolean)
Default: true

If false, then we only enable the popup if the country has the cookie law. We ignore all other country specific rules.

What's New at Osano

Osano partners with SecurityScorecard

Osano has partnered with Security Scorecard, joining its 360° Marketplace launch, enabling customers to amplify their privacy and compliance programs with cybersecurity data. 

Release 2021.6

This release includes language-translation updates to Russian, Chinese Hong Kong (zh-hk) and Chinese Taiwan (zh-tw). 

In addition, this release features enhancements to the Consent Manager experience for users with a right-to-left language.

Release 2021.2.3

This release includes language-translation updates to German, Romanian, Italian, Chinese Hong Kong (zh-hk) and Chinese Taiwan (zh-tw). 

Learn More

Consent Manager now available in 42 languages

Consent Manager has been updated to support auto-translations in Lithuanian, Latvian and Brazilian Portuguese.

We have also enhanced support for right-to-left languages. 

See a full list of supported languages here.

Griswold release

This release features improvements to Osano Consent Management features and search engine optimization metrics. Customers can now choose to turn First-Layer Categories on/off in cookie banners. Also, customers have the ability to toggle Legacy Browser support on/off to improve site performance. 


Consent Manager now available in 39 languages

Consent Manager has been updated to support auto-translations in Croatian and Icelandic. See a full list of supported languages here

Vendor Auto-Following

Enterprise customers can now automatically track the vendors they've identified in Consent Manager. The change allows seamless and constant monitoring of your vendors and eliminates the need to follow them manually. The feature also alerts you to relevant policy changes their vendors have made and changes that could impact your risk.

Pentland release

This release offers new features in consent management and data subject access requests products. This release is named after Alex Pentland, one of the architects of the GDPR.

Pentland Release Notes

Privacy consulting

Osano is now offering privacy consulting in addition to our compliance software. Whether you need an interim privacy officer, a data protection officer or project-specific resources, our privacy consultants are ready to roll their sleeves up for you.

Explore Consulting

Sweeney release

We have just released a major new upgrade to our platform. This update features role-based access controls for your business. Admins will now be empowered to restrict a user's access and control to specific parts of Osano's platform. This release is named after Latanya Sweeney a Harvard privacy researcher and advocate.

Sweeney Release Notes

Westin release

This update includes improvements and enhancements to consent management. This release is named in honor of Alan Westin, the father of modern data privacy law.

Westin Release Notes

White paper: The Osano Data Privacy and Data Breach Link

Announcing a groundbreaking report analyzing the relationship between a company’s privacy practices and their likelihood of experiencing a data breach. The Osano Data Privacy and Data Breach Link reveals a predictive relationship between responsible privacy practices and security outcomes.

Download the White Paper

11,000 vendors and counting!

Osano's proprietary dataset of vendor privacy risk just broke 11,000! We couldn't be more proud! 🎉

Brandeis release

Announcing a massive update to Osano's platform! We completely re-built the consent manager from the ground up. Updates include:
  • Automated script and cookie classifications
  • We've added multi-factor authentication to help further safeguard your Osano account
  • More than a dozen other features, enhancements, and bug fixes

This release is named after Louis Brandeis, one of the original pioneers of data privacy rights. We released an article on our blog about his fascinating life and how it impacted the data privacy world.

Read the Release Notes

Privacy Insider newsletter

Check out Osano's Privacy Insider newsletter! Every Tuesday, Osano sends a synopsis of the week's most interesting news in the world of data privacy.

A lot of change is happening fast. We take the work out of keeping abreast of regulatory and technological developments.


Release 2020.4

April's release features major improvements to our data subject access request (DSAR) forms:

  • Added a forms editor for customization and 
  • Added pre-fillable forms to save you time
  • Added data elements for commonly used fields

This release included a bunch of other enhancements and features.

Read the Release Notes

Osano launches a partnership with Exterro

Osano and Exterro launched a partnership this week to pair Osano’s industry-leading cookie consent management and vendor monitoring with Exterro’s powerful suite of privacy, e-discovery and risk management tools.

Learn More

Covid-19 Update

How will Covid-19 impact Osano? Read a note from our CEO.

Read the Note

Release 2020.3

Minor bug fixes and the ability to more easily manage your own account billing.

Read the Release Notes

Release 2020.2

Engineering has been hard at work adding new features and 🐜🐛🐞 fixing.

· CCPA Opt-Out mode
· CCPA Do-Not-Sell toggle
· IAB framework implementation
Read the Release Notes

New Year - New Consents!

With today's release, Osano customers now have access to:

· Automated real-time scanning of 1st party cookies.
· Automated scheduled deep site scanning
· Embedded 3rd party disclosures.
· Searchable blockchain-based audit log of consents.
Learn about Consent Management

Application Release 2019.5

Osano regularly releases updates. This December update includes new features to help expedite CCPA compliance.

See the full changelog

Application Release 2019.3

Osano regularly releases updates. This November update includes bug fixes, customer feature requests, and improved consent visualizations.

See the full changelog

Application Release 2019.2

Osano regularly releases updates. This October update improves notifications, addresses numerous user interface bugs, and refreshes the entire application.

See the full changelog

Osano Launch

Osano's open-source tools currently help more than 750,000 active websites with their compliance. These numbers make Osano the most pervasive privacy product on the planet. After more than a year of development and testing, you can finally access the Osano suite of applications. We're honored to launch Osano on stage at TechCrunch Disrupt Battlefield.

Watch The Video

7,000 Vendor Milestone

The Osano attorneys have been hard at work and today we are proud to share that we have now evaluated the privacy practices of more than 7,000 companies!

Learn about vendor monitoring

Beta Testing Complete

Thank you to all of the beta testers who participated in the closed beta. The beta has now concluded as we prepare for launch.

Osano Closes $5.4M Series A

Explosive growth and ease of use are a few of the reasons that investors are falling in love with Osano.

Read about our Series A

Osano offers new features on consent management and data subject access controls

Explosive growth and ease of use are a few of the reasons that investors are falling in love with Osano.

Read about our Series A

Osano Closes $5.4M Series A

Explosive growth and ease of use are a few of the reasons that investors are falling in love with Osano.

Read about our Series A