---
title: "Browser API"
description: "Control the consent banner from page JavaScript with the window.CookieBeam runtime API."
url: "https://cookiebeam.com/docs/api-reference/browser-api"
lang: "en"
---

# Browser API

Control the consent banner from page JavaScript with the window.CookieBeam runtime API.

The CookieBeam loader installs a JavaScript API on the page as `window.CookieBeam`. The loader itself calls `run()` with your published configuration, so the methods below are ready to use as soon as the banner script has loaded. Callers that run too early receive an error telling them the runtime has not been initialized.

```html
<script>
  // Show the preferences modal when a "Cookie settings" link is clicked.
  document.getElementById('cookie-settings').addEventListener('click', function () {
    window.CookieBeam.showPreferences();
  });
</script>
```

## Modal control

| Method | Description |
| ------ | ----------- |
| `show(createModal?)` | Show the consent banner. Returns a promise |
| `hide()` | Hide the consent banner |
| `showPreferences()` | Open the preferences modal. Returns a promise |
| `hidePreferences()` | Close the preferences modal |

## Read consent state

| Method | Returns | Description |
| ------ | ------- | ----------- |
| `validConsent()` | `boolean` | Whether the visitor has a valid, current consent record |
| `acceptedCategory(category)` | `boolean` | Whether a category (for example `analytics`) is accepted |
| `acceptedService(service, category)` | `boolean` | Whether a specific service within a category is accepted |
| `validCookie(cookieName)` | `boolean` | Whether the named browser cookie exists and has a non-empty value. **This is not a consent check** — it consults no category, service, or consent state. Use `acceptedCategory` to decide whether a cookie's purpose is allowed |
| `getUserPreferences()` | object | The full preference snapshot: `acceptType`, `acceptedCategories`, `rejectedCategories`, `acceptedServices`, `rejectedServices` |
| `getCookie(field?, cookieName?)` | `unknown` | Read the consent cookie, or one field of it |
| `getConfig(field?)` | `unknown` | Read the active runtime configuration, or one field of it |

## Change consent state

| Method | Description |
| ------ | ----------- |
| `acceptCategory(categories?, excludedCategories?)` | Accept one category, an array of categories, `'all'`, or `'necessary'`, optionally excluding specific categories |
| `acceptService(service, category)` | Accept one service, an array of services, or `'all'` services within a category |
| `reset(deleteCookie?)` | Clear the consent state, optionally deleting the consent cookie as well |

Gate optional scripts on `acceptedCategory` before injecting them, or use the script-gating attributes described in the install docs so the runtime blocks them automatically.

## Utilities

| Method | Description |
| ------ | ----------- |
| `setLanguage(code, forceUpdate?)` | Switch the banner language. Returns a promise resolving to `boolean` |
| `loadScript(src, attrs?)` | Load an external script once, resolving to `true` when it loads. Use it to activate scripts after consent |
| `setCookieData({ value, mode? })` | Store custom data on the consent record; `mode` is `'update'` or `'overwrite'` |
| `eraseCookies(cookies, path?, domain?)` | Delete cookies by name or pattern, optionally scoped by path and domain |
| `run(config?)` | Initialize the runtime. The loader already calls this; calling it again with a new config destroys and recreates the runtime |
| `destroy()` | Tear the runtime down and remove its listeners |

## Support diagnostics

`window.CookieBeamConsent.debugInfo()` returns a diagnostics snapshot of the runtime. It is always attached, even when initialization fails. CookieBeam support may ask you to paste its output when troubleshooting an installation.