ez-consent

ez-consent

🍪 A minimal, vanilla JavaScript cookie consent banner with no dependencies.

• Vanilla JavaScript only ✔️
• It does not track you ✔️
• Very lightweight with no dependencies ✔️
• Single line to get started ✔️
• Supports Google consent mode ✔️

Examples:

• Live example 1
• Live example 2
• CodePen examples

Usage

Quick Start: CDN

The simplest way to get started is to add it to your page:

<script
  type="text/javascript"
  src="https://cdn.jsdelivr.net/npm/ez-consent@^1/dist/ez-consent.min.js"
  defer
  async
  onload="
        ez_consent.init({
            privacy_url: '/privacy',
            texts: {
                buttons: {
                    ok: 'OK',
                    more: 'More',
                },
            },
        });
    "
></script>

See Initialize the script for additional options and alternative ways.

top↑

Advanced Usage

• Import
• Initialize
• Style (optional)

1. Import

Here are some examples how you can install the script:

• Using NPM: npm install ez-consent --save
• Or using yarn: yarn add ez-consent
• Using git submodule (not recommended):
  • Go to the folder you wish to have the repository
  • Run git submodule add https://github.com/undergroundwires/safe-email

Add it to your page:

<script
  type="text/javascript"
  src="/node_modules/ez-consent/dist/ez-consent.min.js"
></script>

Or you can import ez_consent as a module:

<script type="module" async defer>
  import { ez_consent } from './ez-consent/src/ez-consent.js'; // /node_modules/ez-consent/ez-consent.js ...
  ez_consent.init();
</script>

Or import it via webpack, gulp, rollup etc.:

import { ez_consent } from './node_modules/ez-consent/src/ez-consent';

top↑

2. Initialize

When importing a script using the <script> element, it's recommended to use the onload attribute to initialize it. This approach allows you to keep both async and defer attributes, which improve webpage performance and user experience by optimizing script loading. This can help your pages rank better in search engines.

<script
  type="text/javascript"
  src="/node_modules/ez-consent/dist/ez-consent.min.js"
  async
  defer
  onload="
        ez_consent.init({
            privacy_url: '/privacy',
            texts: {
                buttons: {
                    ok: 'OK',
                    more: 'More',
                },
            },
        });
    "
></script>

Or, you can initialize later using this snippet:

ez_consent.init();

See all options:

ez_consent.init({
  is_always_visible: false, // Always shows banner on load, default: false
  privacy_url: '/privacy', // URL that "more" button goes to, default: "/privacy/"
  consent_duration: 'P10Y', // Consent duration (cookie expiry date), default: 10 years. ISO 8601 format, decimals are not supported.
  enable_google_consent_mode: false, // Sends consent state to Google (enables Google consent mode)
  more_button: {
    target_attribute: '_blank', // Determines what the behavior of the 'more' button is, default: "_blank", opens the privacy page in a new tab
    is_consenting: true, // Controls whether clicking the 'more' button automatically gives consent and removes the banner, default: true
  },
  texts: {
    main: 'We use cookies', // The text that's shown on the banner, default: "This website uses cookies & similar."
    buttons: {
      ok: 'ok', // OK button to hide the text, default: "ok"
      more: 'more', // More/accept button that shows the privacy policy, default "more"
    },
  },
  css_classes: {
    // CSS class name overrides
    container: 'container', // Main container element, default: "cookie-consent"
    message_text: 'mainText', // Main message text container, default: "cookie-consent__text"
    buttons: {
      wrapper: 'buttonsWrapper', // Button container, default: "cookie-consent__buttons"
      more: 'moreButton', // More info button, default: "cookie-consent__button cookie-consent__button--more"
      ok: 'okButton', // More/accept button, default: "cookie-consent__button cookie-consent__button--ok"
    },
  },
});

The banner will be shown if the user has not yet agreed to read & understand the information. You can force the banner to always show by including the force-consent query parameter in the URL. Example for https://test.com/fest page: test.com/fest?force-consent.

top↑

3. Style

Existing Themes

You can choose one of the following existing themes to begin:

box-bottom-left.css

Source file | See it live | Preview on CodePen

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/ez-consent@^1/dist/themes/box-bottom-left.min.css"
/>

subtle-bottom-right.css

Source file | See it live | Preview on CodePen

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/ez-consent@1/dist/themes/subtle-bottom-right.min.css"
/>

Custom Themes

Or you can create your own theme & import it. Check example themes at existing themes. The HTML uses only a few classes using BEM naming convention.

You can also add your own class names using css_classes option, see initialization for details.

You're welcome to contribute your theme to the project in ./src/themes folder by creating a pull request 👍.

top↑

Distributed files

The repository and deployed packages include a dist/ folder that adds polyfills to the files and distributes them as:

• minified (.min.js, .min.css) files for production usage
• non-minified (.js, .css) files for debugging

top↑

GitOps

CI/CD is fully automated for this repo using different Git events & GitHub actions.

top↑