Usercentrics

Usercentrics is a Consent Management Platform (CMP) for recording consent choices and controlling third-party services.

useScriptUsercentrics() loads the CMP v3 ("Web CMP") script, types the window.__ucCmp API, and exposes the UC_UI_CMP_EVENT changes needed to trigger other registry scripts.

export default defineNuxtConfig({
  scripts: {
    registry: {
      usercentrics: {
        trigger: 'onNuxtReady',
      }
    }
  }
})

const { proxy } = useScriptUsercentrics()

<script setup lang="ts">
const { proxy } = useScriptUsercentrics()

// noop in development, ssr
// just works in production, client
function handleAction() {
  // use proxy methods here
}
</script>

<template>
  <div>
    <button @click="handleAction">
      Send Event
    </button>
  </div>
</template>

The composable uses these defaults:

• Trigger: onNuxtReady. The script loads after Nuxt hydration, using the module-wide default.
• Bundle and proxy: off. The CMP loads directly from Usercentrics and is not consent-gated.

Access ucCmp through the proxy, or await $script when you need the loaded object.

const { proxy } = useScriptUsercentrics({
  rulesetId: 'your-ruleset-id',
})
function showSettings() {
  proxy.ucCmp.showSecondLayer()
}

Drive consent triggers from Usercentrics

Pair consent.onConsentChange(...) with useScriptTriggerConsent to load any third-party script the moment the user opts in via the Usercentrics banner.

<script setup lang="ts">
import { ref } from 'vue'

const { consent } = useScriptUsercentrics({
  rulesetId: 'your-ruleset-id',
})

const analyticsGranted = ref(false)

if (import.meta.client) {
  consent.onConsentChange(async (detail) => {
    if (detail.type === 'ACCEPT_ALL' || detail.type === 'SAVE') {
      const details = await window.__ucCmp!.getConsentDetails()
      analyticsGranted.value = !!details?.services?.['your-template-id']?.consent?.status
    }
    else if (detail.type === 'DENY_ALL') {
      analyticsGranted.value = false
    }
  })
}

useScriptGoogleAnalytics({
  id: 'G-XXXXXXX',
  scriptOptions: {
    trigger: useScriptTriggerConsent({ consent: analyticsGranted }),
  },
})
</script>

<template>
  <button @click="consent.showSecondLayer()">
    Privacy settings
  </button>
</template>

onConsentChange returns a teardown function for use with onScopeDispose. Its callback receives the raw UC_UI_CMP_EVENT detail, such as { type: 'ACCEPT_ALL' | 'DENY_ALL' | 'SAVE', ... }.

Open the consent UI

Call consent.whenReady() before the CMP's UC_CMP_API_READY event when you need to await initialization. The current helper only listens for the next event; it does not detect a CMP that is already ready, so a later call can remain pending. The other consent helpers call window.__ucCmp when it is present and otherwise return without doing anything.

<script setup lang="ts">
const { consent } = useScriptUsercentrics({
  rulesetId: 'your-ruleset-id',
})

async function logConsent() {
  const cmp = await consent.whenReady()
  console.log(await cmp.getConsentDetails())
}
</script>

<template>
  <button @click="consent.showFirstLayer()">
    Show banner
  </button>
  <button @click="consent.acceptAll()">
    Accept all
  </button>
  <button @click="consent.denyAll()">
    Reject all
  </button>
</template>

Auto Blocking

If your Usercentrics ruleset uses Auto Blocking, set autoblocker: true to inject the autoblocker module ahead of the loader:

useScriptUsercentrics({
  rulesetId: 'your-ruleset-id',
  autoblocker: true,
})

Usercentrics requires the autoblocker to run before other service scripts; see its direct implementation guide. Because the composable adds this option when it runs on the client, verify the ordering in your rendered app before relying on it for consent enforcement.

Partytown

Do not run Usercentrics under Partytown. Its CMP renders DOM overlays and its __ucCmp methods are not configured for worker forwarding.