Widget Behavior
Three independent settings control how the widget behaves:
| Setting | Question it answers | Where you set it |
|---|---|---|
| Behavior | Does the visitor see a visual challenge? | Site settings in the portal |
| Display mode | How is the widget shown on the page? | Your code (data-mode) |
| Start | When does the widget start verifying? | Your code (data-start) |
Behavior
The behavior decides when visitors have to solve a visual challenge. You set it per site in the portal, so you can change it without touching your code.
| Behavior | What visitors see |
|---|---|
| Passive (default) | Visitors are verified in the background and never see a visual challenge. The smoothest experience for your visitors. |
| Adaptive | Visitors are verified in the background. Only when a request looks suspicious is a visual challenge added. This gives you stronger protection against advanced bots without interrupting regular visitors. Available starting with the Growth plan. |
| Always | Every visitor solves a visual challenge. For forms that need the strictest protection. |
Smart difficulty scaling
In every behavior, CaptchaFox scales the difficulty of the verification to the risk of each request. Regular visitors pass quickly, while suspicious traffic has to do considerably more work.
Display mode
The display mode is set with the data-mode attribute or the mode option.
| Mode | Description |
|---|---|
inline (default) | The widget is shown inside your form. |
popup | The challenge opens in a popup instead of inside the widget. |
hidden | No widget is shown. You start the verification yourself, e.g. when the form is submitted. See Hidden Mode. |
Start
The start setting only controls when the widget begins processing. It doesn’t change whether a visual challenge is shown; that is decided by the behavior.
Set it with the data-start attribute or the start option.
| Start | The widget starts processing… |
|---|---|
none (default) | when the visitor clicks the widget. |
focus | as soon as the visitor interacts with the form, e.g. focuses an input field. |
auto | as soon as the widget has loaded. |
<div class="captchafox" data-sitekey="YOUR_SITEKEY" data-start="focus"></div>With focus or auto, verification is usually done before the visitor submits the form, so they don’t have to wait.