Widget options

Here’s the minimal captcha field declaration:

<div class="private-captcha" data-sitekey="abcdef"></div>

Private Captcha widget is automatically initialized on all elements with private-captcha class name.

Attributes

Apart from the required sitekey data attribute, the following optional attributes are supported:

Notes and examples

data-display-mode

• widget is the default display mode of captcha

• popup captcha widget appears relative to the first parent that has a class private-captcha-anchor.

  <form>
      <div class="private-captcha-anchor">
          <div class="private-captcha" data-display-mode="popup" data-sitekey="xyz"></div>
      </div>
      <!-- ... -->
      <button type="button" onclick="window.privateCaptcha.autoWidget.execute()">Click me!</button>
  </form>
  Click me!

• hidden captcha widget is permanently hidden and you need to handle all callbacks yourself. See example.

data-lang

data-lang allows you to show widget localization in your own language. Translations are defined in the widget/js/strings.js file. If translation to your language is not there, feel free to contribute it.

NOTE: by default data-lang attribute’s value is auto which will attempt to get the current page language and fallback to English. If you want widget to have a static language, add this attribute.

Here’s the list of currently supported languages:

• English (en)
• Deutsch (de)
• Español (es)
• Français (fr)
• Italiano (it)
• Nederlands (nl)
• Svenska (sv)
• Norsk (no)
• Polski (pl)
• Suomi (fi)
• Eesti (et)

Here’s how to localize a widget:

@@ -32,7 +32,7 @@
    <div class="private-captcha"
+       data-lang="de" 
        data-sitekey="xyz">
    </div>

data-theme

TIP: Use theme toggle on this website to check how the widget will look like

data-styles

data-styles allows you to override some of the widget styles to better fit into your website’s design, on top of data-theme. Example of override: data-style="--border-radius: .75rem;".

The following variables support overrides (but in general are not encouraged to change).

Colors:

• --dark-color
• --gray-color
• --pie-color
• --background-color
• --checkbox-background-color
• --checkbox-hover-color
• --accent-color
• --warn-color

Spacing:

• --border-radius
• --extra-spacing (adds equal distance from sides and between checkbox and label)
• --label-spacing (“base” distance from checkbox and label)

Additionally, you can change the following CSS properties:

• display (defaults to inline-block, set to block together with height: 100%; to “stretch” widget)
• font-size (defaults to 1rem, change to “scale” widget)

Check few ready-made examples of using these properties here.

data-store-variable

Captcha object, that is created from the widget configuration, provides a number of APIs.

If this is the only captcha widget on a page, you can access this object via window.privateCaptcha.autoWidget.

However, in case of multiple widgets, you can assign this attribute to a variable name and then access it as a field of the HTMLElement.

<div class="private-captcha" data-sitekey="xyz"
    id="pcWidget" data-store-variable="_privateCaptcha"></div>
<!-- Used in the onclick -->
<button type="button" onclick="document.getElementById('pcWidget')._privateCaptcha.execute()">
    Submit
</button>

Events and Callbacks

Element, where private-captcha class is set, will receive various lifecycle events (alternative to Callbacks). All events receive a detail parameter with widget (Captcha Object) and element properties. As an alternative, you can set data attributes with JavaScript handlers (all callbacks receive a single argument which is the Captcha Object itself).

Example

<form>
    <div class="private-captcha" data-finished-callback="onCaptchaSolved">
    </div>
</form>

function onCaptchaSolved(widget) {
    console.log('Solved!');
}

<form>
    <div class="private-captcha" id="myCaptchaWidget">
    </div>
</form>

const captchaElement = document.getElementById('myCaptchaWidget');
captchaElement.addEventListener('privatecaptcha:finish', (event) => console.log(event.detail.element));

Explicit rendering

All the above assumed that when you include the JavaScript privatecaptcha.js, it automatically initializes all of the elements with CSS class private-captcha. However, it’s possible to omit that and instead do it manually in JavaScript.

To achieve that, you need to add parameter ?render=explicit to the script include:

@@ -18,7 +18,13 @@
- <script src="https://cdn.privatecaptcha.com/widget/js/privatecaptcha.js" defer></script>
+ <script src="https://cdn.privatecaptcha.com/widget/js/privatecaptcha.js?render=explicit" defer></script>

Then, you can use function privateCaptcha.render(htmlElement, options) to explicitly render captcha widget. options parameter allows to set properties with the same names as data-attributes above, taking into account the naming convention.