Banner Control

The consent banner and preferences dialog are rendered by the banner UI plugin inside a Shadow DOM. There is no ui.show() or ui.hide() API. Use the consent API and DOM events below to interact with the banner programmatically.

Open preferences

Dispatch a DOM event that the banner plugin listens for:

<a href="#" id="manage-consent">Consent preferences</a>

<script>
  document.getElementById('manage-consent').addEventListener('click', (e) => {
    e.preventDefault();
    window.dispatchEvent(new CustomEvent('optinstack:open-preferences', { bubbles: true }));
  });
</script>

Wait for the SDK before dispatching if your script runs early:

await window.OptinStack.ready;
window.dispatchEvent(new CustomEvent('optinstack:open-preferences', { bubbles: true }));

The event opens the preferences dialog for consent variants that include preferences. Informational banners do not have a preferences dialog, so the event is ignored for that variant.

Reset consent and re-prompt

Call renew() to clear stored consent and reset choices to rule defaults. When hasConsented becomes false, the banner appears again for visitors who had previously consented.

window.OptinStack.renew();

Use this for "Change consent" links or consent expiry flows configured in the dashboard.

Record consent from custom UI

Build your own accept/reject buttons and record decisions through the JavaScript API. The runtime handles script unblocking, persistence, consent record reporting, and Google Consent Mode updates automatically.

// Custom "Accept all" button
document.getElementById('my-accept-btn').addEventListener('click', () => {
  window.OptinStack.acceptAll('api');
});

// Custom partial consent
document.getElementById('my-analytics-btn').addEventListener('click', () => {
  window.OptinStack.choices = {
    necessary: true,
    analytics: true,
    marketing: false,
    preferences: false,
  };
});

Check consent before showing content

Gate custom content on consent state:

await window.OptinStack.ready;

function updateContent() {
  const showAnalytics = window.OptinStack.analytics;
  document.getElementById('analytics-section').hidden = !showAnalytics;
}

window.OptinStack.subscribe(updateContent);
updateContent();

Blocked iframe placeholders

When an iframe is blocked, the runtime shows a placeholder inside the iframe. Customize its HTML with ui.setPlaceholderHTML():

window.OptinStack.ui.setPlaceholderHTML((categories) => {
  return '<button id="accept">Accept to view</button>';
});

Return trusted HTML only. If your placeholder includes dynamic text, escape it before building the string.

From inside the placeholder (same origin as the iframe document), you can post a message to the parent page:

// Accept all consent from inside a blocked iframe placeholder
parent.postMessage({ type: 'optinstack:action', action: 'acceptAll' }, '*');

// Open preferences from inside a blocked iframe placeholder
parent.postMessage({ type: 'optinstack:action', action: 'openPreferences' }, '*');

These messages are only accepted from OptinStack-controlled iframes.

Tracker declaration widget

Render the tracker declaration list on your page (cookie / tracker inventory for the current project):

<div data-optinstack-declaration></div>

await window.OptinStack.ready;
window.OptinStack.ui.renderDeclaration();

Or target a specific element:

window.OptinStack.ui.renderDeclaration('#my-declaration', {
  styles: '.os-cookie-declaration { --os-decl-link-color: #047857; }',
});

The widget is filled from your published tracker inventory and providers, reflects the visitor's current choices, and can open preferences or withdraw optional consent when the banner UI supports it. If the banner plugin has not mounted yet, renderDeclaration returns undefined; wait for ready and retry or re-call after navigation.

See the JavaScript API for full renderDeclaration options.

Server-side consent checks

To authorize backend work based on the same consent the runtime holds, request a short-lived token and verify it with @optinstack/server:

const token = await window.OptinStack.getServerConsentToken();
// Send token to your API (default header: X-OptinStack-Consent)

See JavaScript API → Server consent token.