osano/cookieconsent: A JavaScript Banner That Leaves the Compliance Work to You

What osano/cookieconsent actually solves

The plugin puts a consent notice in front of a visitor and records the answer in the browser. That is the whole job. It does not decide which law applies to a visitor, does not store consent on a server, and does not block third party scripts on its own. The README is unusually direct about this: "To effectively use any open source consent manager, you will need to do GeoIP lookups, adjust the consent types based on visitor location, callback and save consents in a database, and create callbacks to load scripts after consent is granted." The library is the visible half of that stack.

The audience is therefore narrow. It fits a developer who already has a place to persist consent records and who wants the front end handled. It also fits anyone who wants the banner rendered by their own bundle rather than by a vendor script. It does not fit a marketing team looking for a dashboard, and the README says as much: "Unless you specifically need the open source tool, most website owners will be better served by the hosted version." That sentence is the most useful line in the repository for anyone making an adoption decision, because it comes from the maintainer.

Events replaced callbacks in version 4.0

The 3.x line exposed callback hooks for showing, accepting and revoking the banner. Version 4.0 removed them. The README notes that "the initialization style has changed as have the callbacks (they're gone)" and that lifecycle hooks "are now events." The object returned by the constructor is an event emitter, and the documented event names are initialized, error, popupOpened, popupClosed, revokeChoice and statusChanged. The statusChanged handler receives arguments, which the README prints with a spread operator rather than documenting their shape.

That gap matters for anyone porting from 3.x. The callback you used to gate a script on acceptance has to become an event listener, and the payload you receive is not described in the README. The full documentation is linked from the repository at osano.com/cookieconsent/documentation, and that is where the argument list presumably lives. If you are planning a migration, read that page before you delete the old hooks, because the README alone will not tell you what statusChanged hands you.

The constructor takes an options object, and the README's initialization example sets type to "categories". That value is what turns the banner into a category-based choice rather than a simple accept or decline, and it is the setting that most closely matches what GDPR-style consent requires. The README does not enumerate the other accepted values for type, so treat the documentation as the source for that list.

Installing the package and wiring a first banner

The README points first at a configuration wizard on the Osano site, and then lists package manager options. The npm command installs the package under the name cookieconsent. Note that the Yarn line pins major version 3 with an @3 suffix, while npm is unpinned; the package.json in the repository declares version 4.0.0, so the two install paths can land you on different majors. Check what you actually resolved before writing code against the v4 API.

npm install cookieconsent

There is also a Yarn form, a Bower form, and a jsDelivr script tag for loading the build directly from a CDN instead of bundling it.

<script src="https://cdn.jsdelivr.net/npm/cookieconsent@3/build/cookieconsent.min.js"></script>

Once the script is present, the README says you "only need to attach the script as we've bundled everything together now." In a module build you import the default export; in a classic script tag you read it off the window object as CookieConsent. Constructing it returns the instance you attach listeners to.

import CC from "CookieConsent"

const cc = new CC({
  type: "categories"
})

cc.on( "popupClosed", () => console.log( "Popup Closed" ) )
cc.on( "statusChanged", ( ...args ) => console.log( args ) )

What you should see is the banner rendering with category choices, and the listeners firing as the visitor interacts. If nothing renders, the first thing to check is whether the constructor threw, because the README documents an error event that you can subscribe to with cc.on( "error", console.error ).

The compliance gap the library does not close

The hardest limitation is structural rather than technical. A banner that appears to every visitor regardless of location is not a location-aware consent flow, and the README states that using any open source consent manager effectively requires GeoIP lookups and consent types adjusted by visitor location. Version 3.0 added the ability to "GeoLocate and only show the add-on to people in the relevant countries," but that feature is described as part of the 3.x history, and the v4 README does not restate it in the initialization example. If your requirement is to show a different notice in California than in Germany, confirm which version provides that and how it is configured before you build on it.

The second gap is storage. The README lists saving consents in a database as part of the work you must do. Nothing in the repository layout suggests a server component; the top level holds build configuration, source, examples and webpack files. Consent records live in the browser unless you add persistence yourself. For a site that needs to demonstrate what a specific visitor agreed to, that is not enough.

The third gap is script gating. Third party scripts do not stop loading because a banner is on the page. You have to wrap them in the events the library emits. The hosted product is described as doing this "without callbacks but is instead configurable from a dashboard," which is exactly the work the open source version hands back to you.

How it compares with vanilla-cookieconsent and react-cookie-consent

The search terms around this project mix several unrelated libraries, and the distinction is worth stating plainly. vanilla-cookieconsent, published by orestbida, is a separate project with its own repository and its own npm package. It is not a fork of osano/cookieconsent and does not share its API. If you find a tutorial using a different constructor signature or a config object built around categories and services, you are probably reading vanilla-cookieconsent documentation. The two names collide in search results and in package registries, so confirm the package name before installing.

react-cookie-consent is a third project, a React component rather than a framework-agnostic script. The practical difference is bundling and lifecycle. A React component participates in your component tree and re-renders with it. osano/cookieconsent attaches to the page and emits events, which suits server-rendered pages, static sites and any stack that is not React. Choosing between them is mostly a question of whether you want the banner inside your render tree or beside it.

Against the hosted Osano product, the difference is operational. The hosted version is described as multilingual across 38 languages, storing consents with REST API access, and configurable from a dashboard so that developers control what marketing can toggle. The open source library gives you none of that, and the README recommends the hosted version for most website owners. The open source path is for teams that specifically need to self-host the banner logic.

Maintenance, build tooling and licence terms

The repository is not archived, and the last push was on 2026-08-11. That is recent enough that the project is not abandoned, though the release history tells a different story about versioning: the most recent release listed is 3.1.1 from 2019-05-23, described as the initial Osano release, while package.json declares version 4.0.0. The v4 code exists in the tree and the README documents it, but it has not appeared as a tagged release in the list. Plan for that mismatch when you pin a version.

Upgrade cost is concentrated in the 3.x to 4.x transition. Callbacks are gone, replaced by events, and the initialization style changed. Any code that used the old hooks needs rewriting, and the README does not document the argument shape of statusChanged, so the migration cannot be completed from the README alone. Future upgrades carry the usual risk of a major version that is documented in the README before it is released.

Building from source requires Node tooling. The README names Babel, Terser and PostCSS for compiling SCSS and minifying JavaScript, and the package scripts expose npm run build and yarn run build. For local development the README suggests hosting the files with a local webserver, giving python -m SimpleHTTPServer as the example. The examples directory contains seven HTML files covering themes, informational, opt-out, opt-in, location and JavaScript API cases, which is a reasonable starting point for seeing the banner in different modes.

The licence is MIT, which permits commercial use and modification with attribution. Two caveats come from the README itself. Osano is a registered trademark of Osano, Inc., so the licence does not grant you the brand. And the README states that nothing on the Osano site, platform, services or software constitutes legal advice, directing users who need legal assistance to an attorney. The distribution also includes cryptographic software and carries an export control notice referencing ECCN 5D002.C.1; the README advises checking your country's import and re-export rules before use. That is a factual constraint on distribution, not a legal opinion, and it is worth passing to whoever handles your releases.

Editorial conclusion

Adopt osano/cookieconsent if you want a small MIT-licensed banner you control and you are prepared to build the GeoIP lookup, consent storage and script gating yourself. Do not adopt it if you expect the library to make you compliant on its own: the README states that any open source consent manager needs GeoIP lookups, consent types adjusted by visitor location, saved consents and callbacks to load scripts after consent. Before committing, verify which major version the npm package resolves to, because the README's install commands and its v4 initialization example do not agree.

Frequently asked questions

Official sources

1. License: MIT
2. osano/cookieconsent on GitHub
3. Project website
4. README
5. Releases