Configuration

Configure the widget via data-* attributes on the script tag.

Attribute	Default	Description
`data-site-key`	—	Your public site key (required)
`data-theme`	`auto`	Widget theme: `light`, `dark`, or `auto`
`data-api-url`	`https://api.crovly.com`	API endpoint (for self-hosted setups)
`data-lang`	Browser default	Widget language (`en`, `tr`, `ar`, etc.)
`data-size`	`normal`	Widget mode: `normal`, `managed`, or `invisible`
`data-badge`	`on`	Set to `off` to hide "Protected by Crovly" (Pro plan)
`data-primary-color`	—	Custom accent color as hex (e.g. `#6366f1`) (Pro plan)
`data-response-field-name`	`crovly-token`	Name of the hidden input field

<script src="https://get.crovly.com/widget.js"
        data-site-key="crvl_site_xxx"
        data-theme="dark"
        data-lang="en"
        data-size="normal"
        data-badge="on"
        data-api-url="https://api.crovly.com"></script>

Crovly supports three widget modes, controlled via data-size or the dashboard.

Normal Mode (default)

The standard visible widget. Shows a verification spinner, status text, and the "Protected by Crovly" badge.

A compact widget that only shows a small checkbox-style indicator. The verification runs in the background, and the widget shows a checkmark when complete. Ideal for forms where you want minimal visual presence.

<script src="https://get.crovly.com/widget.js"
        data-site-key="YOUR_KEY"
        data-size="managed"></script>

Invisible Mode (Pro)

The widget runs entirely in the background without any visible UI. A hidden input field is still added to the form with the verification token. The widget starts solving the challenge immediately on page load.

<script src="https://get.crovly.com/widget.js"
        data-site-key="YOUR_KEY"
        data-size="invisible"></script>

<form action="/submit" method="POST">
  <div id="crovly-captcha"></div>
  <button type="submit">Submit</button>
</form>

Invisible mode is useful for forms where you want zero visual friction. The user never sees the captcha — verification happens entirely in the background. If the challenge fails, the form submission will not include a valid token, and your backend should reject it.

Managed and invisible modes require a Pro plan. Free users can only use normal mode.

Custom Styling (Pro)

Customize the widget's accent color to match your brand. Set a custom primary color via the data-primary-color attribute or in the dashboard under Sites → [Your Site] → Widget Settings.

<script src="https://get.crovly.com/widget.js"
        data-site-key="YOUR_KEY"
        data-primary-color="#6366f1"></script>

The color is applied to the verification spinner, checkmark, and interactive elements. Accepts any valid hex color (#RRGGBB).

JavaScript API

For advanced use cases, control the widget programmatically using the global Crovly object.

Crovly.render()

Render a widget into a container element.

const widget = Crovly.render('#container', {
  siteKey: 'YOUR_KEY',
  theme: 'dark',
  onVerify: (token) => console.log('Verified:', token),
  onError: (code, message) => console.error(code, message),
  onExpire: () => console.log('Token expired'),
});

Crovly.reset()

Reset the widget and re-run the verification challenge.

Crovly.reset('#container');

Crovly.getResponse()

Get the current verification token. Returns null if the widget has not been verified yet.

const token = Crovly.getResponse('#container');
if (token) {
  // submit the token to your backend
}

Crovly.remove()

Remove the widget from the DOM and clean up all event listeners.

Crovly.remove('#container');

Config Options

All options that can be passed to Crovly.render():

Option	Type	Description
`siteKey`	`string`	Your public site key (required)
`apiUrl`	`string`	API endpoint (default: `https://api.crovly.com`)
`theme`	`'light' \| 'dark' \| 'auto'`	Widget theme (default: `auto`)
`size`	`'normal' \| 'managed' \| 'invisible'`	Widget mode (default: `normal`)
`lang`	`string`	Language code (e.g. `en`, `tr`, `ar`)
`badge`	`boolean`	Show/hide "Protected by Crovly" badge (default: `true`)
`primaryColor`	`string`	Custom accent color as hex (e.g. `#6366f1`)
`responseFieldName`	`string`	Hidden input name (default: `crovly-token`)
`onVerify`	`(token: string) => void`	Called on successful verification
`onError`	`(code: string, message: string) => void`	Called on error
`onExpire`	`() => void`	Called when the token expires

Difficulty Modes

Configure the PoW difficulty in your site settings on the dashboard.

Mode	Difficulty	Solve Time
Auto	16–28	Adapts based on IP reputation
Easy	16	~100ms — minimal friction
Medium	20	~500ms — balanced
Hard	24	~2-5s — high security

Auto is recommended for most sites. It starts with low difficulty for clean IPs and increases for suspicious traffic.

Custom difficulty modes (Easy, Medium, Hard) require a Pro plan. Free users can only use Auto mode.

IP Allowlist / Blocklist

Control which IPs can pass verification for your site. Available on the Pro plan.

Block rules — IPs matching a block rule are immediately rejected (score 0)
Allow rules — When allowlist rules exist, only matching IPs can pass; all others are rejected

Supports IPv4, IPv6, and CIDR notation:

Format	Example	Description
IPv4	`203.0.113.42`	Exact IP match
IPv4 CIDR	`10.0.0.0/8`	Entire subnet
IPv6	`2001:db8::1`	Exact IPv6 match
IPv6 CIDR	`2001:db8::/32`	IPv6 subnet

Configure IP rules in Dashboard → Sites → [Your Site] → IP Allowlist / Blocklist.

CSV Export

Export your analytics data as CSV from the dashboard. Available on the Pro plan.

Analytics page — Export global stats across all sites
Site detail page — Export stats for a specific site

Supported periods: 7 days, 14 days, 30 days. CSV includes: Date, Hour, Site, Total Requests, Passed, Blocked, Avg Score, Avg Solve Time.

Widget Attributes

Widget Modes