Widget Configuration

Customize the CAPTCHA Cat widget's appearance and behavior using HTML attributes and dashboard settings.

Basic Setup#

<div class="captcha-widget" data-sitekey="YOUR_SITE_KEY"></div>
<script src="https://challenge.captchacat.com/ray/widget.js"></script>

HTML Attributes#

Required Attributes

Optional Attributes

Token Callback#

For single-page applications or custom form handling, use the token callback to receive the token directly:

<div class="captcha-widget"
     data-sitekey="YOUR_SITE_KEY"
     data-token-callback="handleToken">
</div>
 
<script>
function handleToken(token) {
  console.log('Token received:', token);
  // Send token to your server
}
</script>

The callback supports nested function names:

// Works with: data-token-callback="myApp.captcha.handleToken"
window.myApp = {
  captcha: {
    handleToken: function(token) {
      // Handle the token
    }
  }
};

Widget Modes#

Configure the widget mode in the Dashboard under Site Settings:

Auto Solve (Default)

The widget automatically runs the verification challenge in the background. Users see a loading animation while the challenge completes.

Click to Solve

Users must click a checkbox to start the verification. This provides a more traditional CAPTCHA experience.

Invisible

The widget runs completely in the background with no visible UI. The verification happens automatically when the form is submitted or when you programmatically trigger it.

Themes#

Configure the theme in the Dashboard under Site Settings:

Light Theme

Clean, light background suitable for light-colored websites.

Dark Theme

Dark background for dark-themed websites.

Adaptive Theme

Automatically detects the parent page's background color and adjusts the widget theme accordingly.

Programmatic Rendering#

For React, Vue, or other SPA frameworks, you can manually render the widget:

// Render into a specific container
const container = document.getElementById('my-captcha-container');
window.Captchacat.render(container);

This is useful when:

• The widget container is dynamically added to the page
• You need to re-render after a form reset
• You're using a framework that manages the DOM

Widget Sizing#

The widget automatically sizes itself based on the form's input fields:

• Matches the width of the widest input field in the parent form
• Minimum width: 280px
• Maximum width: 2000px
• Fixed height: 48px

If the widget is not inside a form, it defaults to 300px width.

Supported Languages#

The widget automatically detects the browser's language and displays messages in:

• English (en)
• German (de)
• Spanish (es)
• French (fr)
• Portuguese (pt)
• Italian (it)
• Dutch (nl)
• Polish (pl)
• Russian (ru)
• Japanese (ja)
• Chinese (zh)
• Korean (ko)

Form Integration#

When placed inside a form element, the widget automatically:

1. Appends a hidden captchacat-token input field when verification succeeds
2. Resets after form submission to allow subsequent submissions

<form action="/submit" method="POST">
  <input type="text" name="name" />
 
  <div class="captcha-widget" data-sitekey="YOUR_SITE_KEY"></div>
 
  <button type="submit">Submit</button>
</form>

After verification, your form will include:

<input type="hidden" name="captchacat-token" value="abc123.1234567890.xyz789">

Retrieving the Token via JavaScript

If you need to access the token value directly in JavaScript (e.g., for AJAX submissions), use querySelector:

// Recommended approach
const token = document.querySelector('input[name="captchacat-token"]').value;

Alternatively, you can use getElementsByName, but note that it returns a collection:

// Returns a NodeList, so you must access the first element
const token = document.getElementsByName("captchacat-token")[0].value;

For programmatic form submissions:

const form = document.getElementById('my-form');
const formData = new FormData(form);
const token = formData.get('captchacat-token');
 
// Or append to existing FormData
formData.append('captchacat-token', token);