Written for Cookie Rocks 2.11.0, checked on 6 November 2026. The current version is 2.11.2: some details may have changed.
What you can do here
- Start your own scripts only once the visitor accepts their category.
- Read or change the visitor’s choice, and open the choices from your own button.
- Make Google Tag Manager tags wait for consent, with two data layer events.
Everything on this page comes with Cookie Rocks Pro, on the pages where its banner is turned on. The free Cookie Rocks Audit adds no script to your visitors’ pages, so it has no JavaScript API and fires no event.
| What | Name | Plugin |
|---|---|---|
| API | window.CookieRocks | Pro |
DOM events, on document | cookie-rocks:ready, cookie-rocks:change, cookie-rocks:ui, cookie-rocks:reload, wp_consent_type_defined | Pro |
Google Tag Manager events, in dataLayer | cr_consent_ready, cr_consent_update | Pro |
| HTML attributes | data-cr-category, data-cr-service, data-cr-type, data-cr-src, data-cr-allow, data-cr-open, data-cr-ignore | Pro |
Other globals you may see in the page (crHead, crConfig, crData, crUi, crEmbeds, crPurge, crPreviewLocale) are internal and may change. Do not use them.
When the API is ready
The script of the banner loads with defer. It creates window.CookieRocks, applies the stored choice and fires cookie-rocks:ready, before DOMContentLoaded. A script that runs earlier, such as an inline script in the page, does not see window.CookieRocks yet. This helper works in both cases:
function whenCookieRocks(callback) {
if (window.CookieRocks) {
callback();
} else {
document.addEventListener('cookie-rocks:ready', callback, { once: true });
}
}
whenCookieRocks(function () {
CookieRocks.onConsent('statistics', function () {
// Start your own statistics tool here.
});
});There is no window.CookieRocks when the banner is turned off, and on pages opened in a page builder.
window.CookieRocks
| Method | What it does |
|---|---|
CookieRocks.open() | Opens the details panel, and loads its code first if needed. |
CookieRocks.acceptAll() | Records “Accept all”. Marketing stays refused when the site honours Global Privacy Control and the browser sends it, or when the signed-in account refused it. On a site for children, marketing and statistics stay refused. |
CookieRocks.rejectAll() | Records “Reject all”: every optional category is refused, and the tools allowed one by one are withdrawn too. |
CookieRocks.allowService(id) | Allows one tool of the catalogue on its own, for example 'youtube'. |
CookieRocks.hasChoice() | true once the visitor has answered the banner. |
CookieRocks.hasConsent(category, service) | true if the category is accepted. See below. |
CookieRocks.getConsent() | The state of each category: {necessary, preferences, statistics, marketing, audience}, as booleans. |
CookieRocks.getServices() | The ids of the tools allowed one by one. |
CookieRocks.setProfile(profile) | Sets the rules that apply to the visitor, with Rules by country. Cookie Rocks calls it itself once it knows the visitor’s country: leave it to Cookie Rocks, unless you locate visitors with your own code. profile.p is strict or objection. |
CookieRocks.onChange(callback) | Calls callback(consent, services) after each choice. |
CookieRocks.onConsent(category, callback) | Calls callback at once if the category is already accepted, otherwise once, when it is accepted. |
In hasConsent and onConsent, category is necessary, preferences, statistics, marketing or audience. The aliases analytics (statistics), ads and advertising (marketing) and functional (necessary, so always accepted) work too. A comma-separated list, such as 'statistics,marketing', means any one is enough. With the optional service id, hasConsent also returns true when that tool was allowed on its own.
if (CookieRocks.hasConsent('marketing', 'youtube')) {
// The visitor accepted marketing, or allowed YouTube on its own.
}
document.querySelector('.my-settings-link').addEventListener('click', function (event) {
event.preventDefault();
CookieRocks.open();
});When a choice takes back a consent given earlier, Cookie Rocks deletes the matching cookies and browser storage, then reloads the page: a script already running cannot be stopped. Allowing a tool that must be there when the page loads, such as a captcha, reloads the page too, and keeps what the visitor typed in the forms.
DOM events
These events are dispatched on document.
| Event | When | event.detail |
|---|---|---|
cookie-rocks:ready | On each page load, once the stored choice is applied. | {consent, services, given} |
cookie-rocks:change | After each choice: banner, details panel, API, the button of a video or map, or a data-cr-allow element. | {consent, services, given} |
cookie-rocks:ui | When the code of the banner and the details panel has loaded: at the first visit, or when the visitor reopens the choices. | None |
cookie-rocks:reload | Just before the page reloads to load a tool allowed on its own that must be there when the page loads, such as reCAPTCHA. Cookie Rocks uses it to keep what the visitor typed in the forms. | {consent, services, given} |
wp_consent_type_defined | On each page load and after each choice, after the choice is passed to WP Consent API when that plugin is active (a convention of WP Consent API). Cookie Rocks also sets window.wp_consent_type to optin, or optout when the banner only informs. | None |
In detail, consent is the object returned by getConsent(), services is the array of tools allowed one by one, and given says whether the visitor has answered the banner.
document.addEventListener('cookie-rocks:change', function (event) {
if (event.detail.consent.marketing) {
// Marketing is accepted.
}
});Google Tag Manager events
These events are pushed to dataLayer.
| Event | When | Variables |
|---|---|---|
cr_consent_ready | On every page, from the script in the page head, before the Google tags. | cr_consent (the state of each category, as booleans), cr_consent_status (given or pending) |
cr_consent_update | After each choice, including a tool allowed on its own. | cr_consent, cr_services (tools allowed one by one), cr_consent_status |
In Google Tag Manager, use a Custom Event trigger on cr_consent_update (and cr_consent_ready), with a Data Layer Variable cr_consent.marketing or cr_consent.statistics equal to true. See Google Consent Mode, Tag Manager and Site Kit.
// What Cookie Rocks pushes after a choice:
{
event: 'cr_consent_update',
cr_consent: { necessary: true, preferences: false, statistics: true, marketing: false, audience: false },
cr_services: [],
cr_consent_status: 'given'
}Hold your own scripts and frames
Known cookies are held on their own. For another script, give it the type text/plain and a category. Cookie Rocks runs it once the visitor accepts that category:
<script type="text/plain" src="https://example.com/tool.js"></script>
<script type="text/plain">/* inline code */</script>
<script type="text/plain" src="https://example.com/module.js"></script>
<iframe></iframe>| Attribute | On | Effect |
|---|---|---|
data-cr-category | <script type="text/plain">, <iframe> | The category that releases the element. Same names and aliases as hasConsent; a comma-separated list means any one is enough. The data-category attribute is read too. |
data-cr-service | Same | A tool id of the catalogue: the element also runs when that tool alone is allowed. |
data-cr-type | <script> | The type the script gets when it runs, such as module. |
data-cr-src | <iframe> | The address the frame loads once allowed. Without src, the frame stays empty until then. |
data-cr-ignore | <script>, <link rel="stylesheet"> | The automatic blocking leaves this script or stylesheet alone, even if it matches a known tool. Use it only for code that sets no cookie and sends no personal data, or that the law lets load without consent. It does not apply to iframes. |
data-cr-allow | Any element | A click allows the tool named in the attribute, for example data-cr-allow="youtube". |
data-cr-open | Any element | A click opens the details panel. The value sale opens the “Do Not Sell or Share” view instead, on sites that address the United States. A link to #cr-preferences and an element with the class cr-open-preferences work too. See Shortcodes. |
Once consent is given, held scripts download together, then run in the order of the page. An external script is awaited before the next one runs, for 3 seconds at most: code that calls a tool right after its script should wait for that tool to be ready (its own callback, or the load event of its script). Scripts with a type that never runs, such as application/ld+json, are never touched. When a held script belongs to a category no cookie of your site uses, the details panel still shows that category on the pages where the script is.
<button type="button">Allow YouTube videos</button>A frame you write by hand with data-cr-src stays blank until consent. The short request with a button appears only in the frames that Cookie Rocks holds itself. To get it, keep the normal src of a known provider, and let Cookie Rocks hold the frame.