There are two ways to configure a widget: HTML attributes on the element (when you use the script tag), or options passed to CDPCaptcha.createWidget() (when you create widgets from JavaScript).
HTML attributes
| Attribute | Meaning | Example |
|---|---|---|
data-sitekey | Required. The public sitekey of the website. | data-sitekey="…" |
data-start | When solving starts. auto: as soon as the widget is mounted. focus: on the first focus inside the surrounding form or on click (default). none: only on click or on start(). | data-start="auto" |
data-theme | light (default), dark, or auto (follows the operating system setting). | data-theme="dark" |
lang | Forces a widget language. Without it the widget uses the nearest lang attribute above it, then the browser language, then English. | lang="de" |
data-form-field-name | Name of the hidden field. Default cdp-captcha-solution. | data-form-field-name="captcha" |
data-api-endpoint | Base of the API, for installations under another host than the script. Default: the host the script was loaded from, plus /api/v1. | data-api-endpoint="https://captcha.example.com/api/v1" |
data-width | Width of the widget (CSS length). Default 320px; 100% fills the form column. | data-width="100%" |
HTML
<div class="cdp-captcha" data-sitekey="YOUR_SITEKEY" data-start="auto" data-theme="auto" lang="de" data-width="100%"></div>JavaScript options
| Option | Type | Meaning |
|---|---|---|
element | HTMLElement | Required. The element to mount on. |
sitekey | string | Required unless the element has data-sitekey. |
startMode | "auto" | "focus" | "none" | Default "focus". |
language | string | "en" or "de"; see Languages. |
theme | "light" | "dark" | "auto" | Default "light". |
formFieldName | string | Default "cdp-captcha-solution". |
apiEndpoint | string | Base URL of the API. |
width | string | CSS length. |
JavaScript
const widget = CDPCaptcha.createWidget({
element: document.querySelector('#captcha'),
sitekey: 'YOUR_SITEKEY',
startMode: 'auto',
theme: 'auto',
language: 'en'
});Widget mode (set on the server)
The start mode decides when solving begins.
Whether the widget completes on its own or needs one click is the widget mode, and it is configured per sitekey in your account, not in the HTML, so a bot cannot change it:
- Zero-click (default): the widget completes as soon as the puzzle is solved.
- One-click: the widget solves in the background but shows "Click to finish the check" and completes on that click (or on form submit).
Several widgets on one page
Each element gets its own widget and its own hidden field.
Widgets inside different forms are independent.
Use data-form-field-name if two widgets share one form.