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-start-mode

• auto (puzzle is obtained and solving starts when parent form receives focus)
• click (puzzle and solving starts when user explicitly clicks the widget)
• load (puzzle and solving starts when the widget initializes/renders)

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.

  NOTE: popup style is recommended to use with data-start-mode="click" for security purposes

  <form>
      <div class="private-captcha-anchor">
          <div class="private-captcha" data-sitekey="xyz"
               data-display-mode="popup" data-start-mode="click"></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)
• Українська (uk)
• Türkçe (tr)

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
• --checkbox-border-color
• --accent-color
• --warn-color

Spacing:

• --border-radius
• --widget-padding
• --logo-margin (distance between logo and “Private Captcha” text)
• --extra-spacing (adds equal distance from sides and between checkbox and label)
• --label-spacing (“base” distance from checkbox and label)

Size:

• --logo-size
• --control-size (size of the checkbox and progress circle)

Additionally, you can change the following CSS properties:

• --logo-direction (column by default, can be set to row for “squished” widgets)
• 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>

data-state

This is a read-only attribute that can have values empty, error, loading, ready, inprogress, verified and invalid. You can use it for CSS conditions.

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.

Unbranded widget

It is possible to use the standard widget, but without Private Captcha logo. For SaaS version that comes as an addon and for self-hosted version it comes with an Enterprise version.

In both cases you need to add an argument branding to the include of privatecaptcha.js script on your website. For SaaS version you will see a branding ID in every integration snippet and for self-hosted version you need to pass none instead of the ID.

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