Skip to Content
Guides & ReferenceWidget Behavior

Widget Behavior

Three independent settings control how the widget behaves:

SettingQuestion it answersWhere you set it
BehaviorDoes the visitor see a visual challenge?Site settings in the portal
Display modeHow is the widget shown on the page?Your code (data-mode)
StartWhen 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.

BehaviorWhat visitors see
Passive (default)Visitors are verified in the background and never see a visual challenge. The smoothest experience for your visitors.
AdaptiveVisitors 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.
AlwaysEvery 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.

ModeDescription
inline (default)The widget is shown inside your form.
popupThe challenge opens in a popup instead of inside the widget.
hiddenNo 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.

StartThe widget starts processing…
none (default)when the visitor clicks the widget.
focusas soon as the visitor interacts with the form, e.g. focuses an input field.
autoas 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.

Last updated on