Install
This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.
Install straight from GitHub with WP-CLI:
wp plugin install https://github.com/web-presence-dev/wordpress-cookie-consent/archive/refs/heads/main.zipA WordPress plugin that shows a cookie consent banner and blocks GA4 and other tracking until the visitor agrees. It recognises the common trackers automatically, includes Google Consent Mode v2, and has a site scanner for anything else. Updates come from this private repo's GitHub releases, through Composer or the plugin's own updater (see Updates and releases).
Quick start
- Install. Composer sites: see Installing. Otherwise, download
webpresence-cookie-consent.zipfrom the latest release (you need access to the repo). In WordPress, go to Plugins → Add New → Upload Plugin, choose the zip, then Install Now → Activate. To get updates in the dashboard, also add a GitHub access token. - Set up Google. Open Cookie Consent in the admin menu. On General:
- Add your GA4 Measurement ID if you want the plugin to add GA4. Leave it empty if GA4 is added another way.
- Keep Google mode on Basic.
- Choose your cookie policy page.
- Save.
- Match the brand. On Appearance, pick the banner position, colours and font, and check the wording. The preview updates as you go. Save.
- Find everything else. On Scanner, click Scan site. Anything marked Unknown needs a category (so it's blocked) or Necessary (so it isn't).
- Let visitors change their mind. Add
[cookie_settings]to the footer or the cookie policy page. You can also add a menu link to#cookie-settings, or switch on the floating button under Appearance. - Check it. Open the site in a private window. The banner shows, and nothing from Google, Meta and so on loads until you accept (see Checking it works).
That's it. Known trackers are blocked automatically, and updates show on the Plugins screen when a new release is published.
Contents
- Quick start
- Requirements
- Installing
- Settings
- Opening the preferences: shortcode and classes
- Styling: using your theme's buttons and CSS
- How blocking works
- The scanner
- For developers: events, filters and the JS API
- Updates and releases
- Local development
- Moving a site off the webpresence theme's banner
Requirements
- WordPress 6.5+
- PHP 8.1+
No other plugins are needed. ACF isn't required.
Installing
The repo is private, so every install route needs GitHub access: your own login to download a zip, or a read-only access token for servers.
With Composer (the webpresence site, and any site deployed from Git)
Use this for sites where DISALLOW_FILE_MODS is on (Tesla sets it on production), because WordPress can't install updates on those.
-
Add the repo and the package to the site's
composer.json:"repositories": { "cookie-consent": { "type": "vcs", "url": "https://github.com/Web-Presence-Dev/Wordpress-Cookie-Consent" } }, "require": { "web-presence-dev/wordpress-cookie-consent": "^0.1" }The webpresence site already has a
repositoriesobject (Satispress, WP Packagist); addcookie-consentbeside those. The package installs towp-content/plugins/webpresence-cookie-consent/, which that site's.gitignorealready ignores. -
Give Composer the token. On each machine that runs
composer install(the Forge server, CI, your laptop):composer config --global --auth github-oauth.github.com github_pat_…That writes it to Composer's own
auth.json, the same file Satispress's credentials live in on the server. Never commit it. -
composer update web-presence-dev/wordpress-cookie-consent, commitcomposer.lock, and deploy as usual.
Getting an update onto the site: after a new vX.Y.Z tag is released, run composer update web-presence-dev/wordpress-cookie-consent locally, commit composer.lock and deploy. The deploy script's composer install picks up the new version. With ^0.1 you get every 0.1.x; change the constraint to move to 0.2.
Local development: if the plugin is symlinked into the local site (see Local development),
composer installthere replaces the link with the released copy, so you'd stop seeing your edits. Re-create the link after running Composer locally.
From a zip (sites managed in the dashboard)
- Download
webpresence-cookie-consent.zipfrom Releases (signed in to GitHub with access to the repo). - In WordPress, go to Plugins → Add New → Upload Plugin, upload it and activate it.
- Add an access token so the site can see and install updates.
Settings
The Cookie Consent menu has six tabs.
General
| Setting | What it does |
|---|---|
| Show the banner and block tracking | Master switch. When off, nothing is blocked and no banner shows. |
| GA4 Measurement ID | Optional. Set it to let the plugin add GA4 itself. Leave it empty if GA4 is added another way (Site Kit, GTM, the theme). It's blocked either way. |
| Google mode | Basic (default): Google tags don't load at all until consent. Advanced: Google tags load but set no cookies until consent, and send cookieless pings for modelling. |
| Remember a choice for | Days before the banner asks again (max 395; 365 is the usual). |
| Cookie policy page / URL | Linked from the banner and dialog. Falls back to the privacy policy page. |
| Ask everyone again | Bumps the consent version, so every visitor sees the banner again. Do this after adding new tracking. |
Appearance
Everything here is applied as CSS custom properties, so there's no theme CSS to edit.
- Position: card bottom-left, card bottom-right, full-width bar, or centred pop-up.
- Floating button: an optional round "Cookie settings" button shown after a choice is made.
- Font: same as the theme (default), the system font, or a custom family. A custom family must be a font the theme already loads; the plugin doesn't load fonts.
- Text size and corner radius for the banner and pop-up.
- Buttons: the plugin's own style (colours below, plus a corner setting from square to pill), or Use my theme's buttons with your theme's classes. See Styling.
- Colours: background, text, links, main buttons, outline buttons, the switch's "on" colour and the dialog backdrop. Optionally set a second dark mode palette, used when the visitor's device is in dark mode.
- Wording: every piece of text on the banner, dialog and blocked-embed placeholders.
A live preview on the right updates as you change things, before you save. It's rendered by the site's theme, so fonts and theme buttons look exactly as they will on the site. Use its Light/Dark buttons to check both palettes.
Categories & services
- Categories: Functional, Analytics and Marketing, each with an editable label and description. "Strictly necessary" is always on. If you switch a category off, it disappears from the banner and its services are blocked under the strictest category that's left.
- Known services: everything the plugin recognises. You can change the category a service is blocked under, or choose Don't block for one the site needs to work.
- Custom rules: block anything whose script URL, embed URL or inline code contains some text, e.g.
cdn.some-tracker.com.
Scanner
See The scanner.
Tools
Copy settings to another site. Export settings downloads a .json file of every setting: appearance, colours, wording, categories, services and custom rules. Import settings applies that file on another site, so it's set up the same way.
- Every value goes through the same checks as the settings forms.
- The cookie policy page is matched by its address (e.g.
/cookies/). If there's no such page, you're told to choose one on the General tab. - The site's consent version is kept, so visitors aren't asked again.
Updates
Shows the installed and latest versions and the release notes. Check for updates now clears the 12-hour cache.
Opening the preferences
Visitors must be able to change their mind at any time, so put a way to reopen the preferences somewhere on every page. The footer is the usual place.
Shortcode
[cookie_settings]
Attributes:
| Attribute | Default | |
|---|---|---|
text |
"Cookie settings" (from Appearance → Wording) | Button text |
type |
button |
link makes it look like a text link |
class |
— | Your own classes. When set, the plugin's button styles are left off, so the theme can style it |
Examples:
[cookie_settings]
[cookie_settings type="link" text="Change cookie settings"]
[cookie_settings class="footer__link"]
In a PHP template: <?php echo do_shortcode('[cookie_settings class="footer__link"]'); ?>
[wpcc_preferences] is an alias.
Without the shortcode
Any of these opens the dialog too:
- a link to
#cookie-settings, which works in WordPress menus (add a Custom Link with URL#cookie-settings) - any element with the class
wpcc-open - any element with the class
js-cookie-settings, which keeps the webpresence theme's existing footer button working window.wpccOpenPreferences()from JavaScript
Styling: using your theme's buttons and CSS
Most sites only need Appearance in the settings. When the banner has to match a theme exactly, there are three levels, from simplest to most flexible.
1. Use your theme's button classes (no code)
Cookie Consent → Appearance → Buttons → Use my theme's buttons, then enter the classes your theme uses:
| Setting | Example |
|---|---|
| Main button classes | button (or btn btn-primary) |
| Outline button classes | button button--outline |
The plugin then drops its own button styles: the Buttons colours and the button-corner setting are hidden and ignored. Main buttons are Accept all, Reject all, Save choices, "Allow and load" and the [cookie_settings] button; outline buttons are Accept all and Reject all in the preferences pop-up.
The settings preview is rendered by your theme (it's a small front-end page shown in a frame), so it shows the buttons, fonts and colours exactly as visitors will see them.
2. Replace the button markup (PHP filter)
Some theme buttons need more than a class, such as an icon or a label wrapper. The wpcc_button_html filter lets the theme supply the whole button:
add_filter('wpcc_button_html', function (string $html, array $args): string {
// $args: action, label, variant ('primary' | 'secondary'), attributes, class
return sprintf(
'<button %s class="%s">%s</button>',
$args['attributes'], // required: type="button" and data-wpcc-action
$args['class'], // required: the plugin's classes + your setting's classes
esc_html($args['label'])
);
}, 10, 2);
Keep $args['attributes'] and $args['class'] on the element. The plugin's script uses them to find each button, and without them the button stops working. $args['label'] isn't escaped, so escape it.
Example: the Web Presence theme
The webpresence theme's buttons are .button / .button--outline, with a label span and an arrow icon. To use them:
-
Settings: switch on Use my theme's buttons, with main classes
buttonand outline classesbutton button--outline. -
In the theme, e.g.
lib/Theme/consent.php(which replaces the old built-in banner code):use Turing\Theme\Markup; add_filter('wpcc_button_html', function (string $html, array $args): string { return sprintf( '<button %s class="%s"><span class="button__label">%s</span><span class="button__icon">%s</span></button>', $args['attributes'], $args['class'], esc_html($args['label']), Markup::svg('arrow') ); }, 10, 2);
This is the same markup the theme's own Markup::button() produces, so the banner's buttons pick up the theme's hover animation and arrow.
3. CSS overrides
The theme's stylesheet can restyle anything. The plugin's selectors:
| Part | Selector |
|---|---|
| Banner | .wpcc-banner (plus .wpcc-banner--card-left, --card-right, --bar, --modal) |
| Preferences pop-up | .wpcc-dialog, inner .wpcc-dialog__inner |
| Plugin buttons | .wpcc-button, .wpcc-button--primary, .wpcc-button--secondary |
| Theme buttons (setting on) | .wpcc-btn, .wpcc-btn--primary, .wpcc-btn--secondary |
| "Manage preferences" link | .wpcc-link |
| Category switches | .wpcc-switch |
| Floating button | .wpcc-floating |
| Blocked-embed placeholder | .wpcc-placeholder |
The settings are CSS custom properties, so the theme can also set them directly, e.g. to follow its own dark mode:
:root {
--wpcc-primary-bg: var(--color-orange);
--wpcc-primary-text: #fff;
--wpcc-button-radius: 999px;
}
[data-theme="dark"] {
--wpcc-bg: var(--color-navy);
--wpcc-text: var(--color-cream);
}
The full list: --wpcc-bg, --wpcc-text, --wpcc-link, --wpcc-primary-bg, --wpcc-primary-text, --wpcc-primary-hover-bg, --wpcc-primary-hover-text, --wpcc-secondary-bg, --wpcc-secondary-text, --wpcc-secondary-border, --wpcc-dialog-bg, --wpcc-dialog-text, --wpcc-dialog-link, --wpcc-switch-on, --wpcc-backdrop, --wpcc-floating-bg, --wpcc-floating-icon, --wpcc-font, --wpcc-font-size, --wpcc-radius, --wpcc-button-radius.
The plugin prints its values on :root in the page <head>. To win over them, use a more specific selector (html:root, or a class on <html>), or load your CSS after the plugin's.
How blocking works
- In the HTML (server). An output buffer rewrites matching tags before the page is sent:
- `