CAPTCHA Widget Overview

Here we explain how the TrustCaptcha CAPTCHA widget can be integrated and customized into any website frontend.

You can use TrustCaptcha with all common technologies and frameworks based on JavaScript. Supported is server-side Rendering (SSR), static site generation (SSG), and single-page applications (SPA). There is a pure JavaScript library. Separate NPM packages exist for Angular, React, and Vue.js.

This is how (or similarly) the implementation of the TrustCaptcha component on your website can look. Please refer to the respective tutorial that matches your programming language or framework.

<form>

  <!-- your input fields -->

  <trustcaptcha-component
    sitekey="<your_site_key>"
    (captchaSolved)="handleSuccess($event.detail)"
    (captchaFailed)="handleError($event.detail)"
  ></trustcaptcha-component>

  <!-- further input fields / submit button -->

</form>

The TrustCaptcha component contains a range of properties, methods, and events. Below you’ll find a listing of all existing ones.

Here is an overview of all available properties, methods, and events of the CAPTCHA widget.

This is a pseudocode example with most of the available properties and events.

<form>

  <!-- your input fields -->

  <trustcaptcha-component
    sitekey="<your_site_key>"
    width="fixed"
    language="en"
    theme="light"
    autostart
    license="<license-key>"
    hide-branding
    custom-translations='[{"language":"en","boxCompleted":"I am a happy human"}]'
    custom-design='{"theme":{"light":{"boxDefaultBackground":"#eab308"}}}'
    privacy-url="https://www.example.com/my-privacy-policy"
    invisible
    invisible-hint="inline"
    token-field-name="tc-verification-token"
    bypass-token="&lt;bypass-token&gt;"
    mode="standard"
    (captchaStarted)="handleStart()"
    (captchaSolved)="handleSuccess($event.detail)"
    (captchaFailed)="handleError($event.detail)"
  ></trustcaptcha-component>

  <!-- further input fields / submit button -->

</form>

Here you will find helpful tips and tricks about integrating the TrustCaptcha component into your frontend.

By default, the verification process starts automatically as soon as a user interacts with the input fields that are in the same form as the CAPTCHA widget. To disable autostart, simply set the property autostart="false" directly on the TrustCaptcha component.

<form>

  <!-- your input fields -->

  <input id="input1" name="input1">

  <input id="input2" name="input2">

  <trustcaptcha-component
    sitekey="<your_site_key>"
    autostart="false"
  ></trustcaptcha-component>

  <!-- further input fields / submit button -->

</form>

It is also possible to disable the autostart trigger only for certain input fields.

<form>

  <!-- your input fields -->

  <input id="input1" name="input1">

  <input id="input2" name="input2" data-autostart="false">

  <trustcaptcha-component
    sitekey="<your_site_key>"
  ></trustcaptcha-component>

  <!-- further input fields / submit button -->

</form>

The custom-translations attribute allows you to specifically override existing translations or add entirely new languages. It is a list of objects where each language is defined by the mandatory language field. Additionally, visible texts can be customized individually.

The translation object looks like this:

{
  "language": "en",
  "boxStart": "Start verification",
  "boxInProgress": "Verification in progress",
  "boxCompleted": "I am a human!",
  "endPrivacyPolicy": "Privacy",
  "ariaLabelStart": "CAPTCHA not started, click here to start the CAPTCHA",
  "ariaLabelRunning": "CAPTCHA in process",
  "ariaLabelDone": "CAPTCHA completed",
  "srRunning": "CAPTCHA verification started",
  "srDone": "CAPTCHA verification successfully completed",
  "srFailed": "CAPTCHA has failed due to a technical error. Please contact the support.",
  "srTrustcaptcha": "Go to the TrustCaptcha website",
  "srPrivacy": "Go to the privacy policy"
}

If an existing language is overridden, unspecified texts remain unchanged. For new languages, English serves as the default, and only the specified texts are added. The new translation texts can be passed to the TrustCaptcha component as follows.

Custom translations usage (plain HTML)

<trustcaptcha-component
  sitekey="<your_site_key>"
  language="en"
  custom-translations='[{ "language": "en", "boxCompleted": "I am a happy human" }]'
></trustcaptcha-component>

Custom translations usage (Angular property binding)

public customTranslations = JSON.stringify([
  {
    language: "en",
    boxCompleted: "I am a happy human"
  }
]);

<trustcaptcha-component
  sitekey="<your_site_key>"
  language="en"
  [customTranslations]="customTranslations"
></trustcaptcha-component>

The custom-design attribute allows you to customize the existing design of the TrustCaptcha component.

The design object looks like this:

{
  "rounding": {
    "box": "6px",
    "checkbox": "6px",
    "invisibleHint": "6px"
  },
  "theme": {
    "light": {
      "boxDefaultBackground": "#f9fafb",
      "boxDefaultText": "#374151",
      "boxDefaultBorder": "#d1d5db",
      "boxCheckboxBackground": "#ffffff",
      "boxCheckboxBorder": "#d1d5db",
      "boxSuccessBackground": "#f9fafb",
      "boxSuccessBorder": "#86efac",
      "invisibleHintBackground": "#ffffff"
    },
    "dark": {
      "boxDefaultBackground": "#1f2937",
      "boxDefaultText": "#e5e7eb",
      "boxDefaultBorder": "#374151",
      "boxCheckboxBackground": "#030712",
      "boxCheckboxBorder": "#374151",
      "boxSuccessBackground": "#1f2937",
      "boxSuccessBorder": "#15803d",
      "invisibleHintBackground": "#1f2937"
    }
  }
}

Only properties explicitly specified will be changed; all others retain default values. The design customizations can be passed to the TrustCaptcha component as follows.

Custom design usage (plain HTML)

<trustcaptcha-component
  sitekey="<your_site_key>"
  license="<license-key>"
  custom-design='{ "theme": { "light": { "boxDefaultBackground": "#eab308" } } }'
></trustcaptcha-component>

Custom design usage (Angular property binding)

public customDesign = JSON.stringify({
  theme: {
    light: {
      boxDefaultBackground: "#eab308"
    }
  }
});

<trustcaptcha-component
  sitekey="<your_site_key>"
  license="<license-key>"
  [customDesign]="customDesign"
></trustcaptcha-component>

When the CAPTCHA widget is completely solved, the CAPTCHA returns a so-called verification token. This is a simple text/string. It is available in a hidden input field called tc-verification-token and is also propagated by the trustcaptcha component with the captchaSolved JavaScript event.

Send this token to your backend. For example, when the form containing the CAPTCHA is submitted, or independently via an API interface. With the help of the verification token, you can now retrieve the CAPTCHA verification result from our servers on the server side. Either via an API interface or with the help of one of our ready-made integrations. You can find out more about this in the result validation overview.

If the CAPTCHA widget is not installed and configured correctly, or if an error occurs during the verification process, the TrustCaptcha component returns an error message via the captchaFailed event. You can use this to determine further steps or to correct the error directly. You can access the error message via $event.detail.

The error model looks like this:

{
  errorCode: 'UNKNOWN_ERROR',
  message: 'Unknown error.'
}

The error message includes an error code named errorCode. This provides information about the actual error and can be used to directly correct the error or to implement error handling.