ReCaptchaV2 Supports ReCaptchaV3

Jan 1, 2019

ReCaptchaV2 Supports ReCaptchaV3

The ReCaptchaV2 (version 3.x) MODX Extra has been refactored to support ReCaptchaV3 as well as maintain backwards compatibility. In fact, you can use both ReCaptcha versions in the same MODX site at the same time, on different forms.

Also included in the new version is an improved implementation of the "Invisible" style of ReCaptchaV2.

The Extra can be installed via the Extras Installer or you can download directly from the MODX Extras repo.

More details can be found in the README. Also, here's a collection of ReCaptcha-related blog posts.

What's new?

System Settings

Site Keys

Google's ReCaptcha service requires site keys and secrets to be generated for each style of ReCaptcha. As such, the Extra now has System Settings for both V2 and V3. They can be used concurrently.

Action Key

ReCaptcha V3 introduces the concept of "Actions". See the ReCaptcha documemtation for more details. The recaptcha-action parameter is sent to the "recaptchav3" hook on form submission (if you add it to the FormIt &hooks property) via a hidden input element in the included "recaptchav3_html" Chunk. The name attribute of the hidden input can be configured in a new System Setting recaptchav3.action_key. You can also set the property in your FormIt call.

Token Key

There's an input for the token returned by ReCaptcha, which similarly needs to be passed in the form submission. You can configure the input name via the System Setting recaptchav3.token_key. You can also set the property in your FormIt call.



This is the V3 version of the the hook. Add it to the FormIt &hooks property as you did with V2's hook. It's aware of the new System Settings and sends the appropriate payload to the ReCaptcha API. As of this writing it hasn't been tested with Login yet—help wanted, please :)


This defaults to rendering the new "recaptchav3_html" Chunk, and passes in the required properties, using the new System Settings. It also sets a default form\_id if none is provided, because V3 uses it as the value for recaptcha-action.



As with the V2 Chunks, this can be customized to change the implementation completely, if your needs differ from the basic use case I've contemplated. When customizing Chunks that come with Extras, it's always good practice to rename them so your custom markup isn't overwritten on updates.

Example Usage

Check out the README for example FormIt calls, including multiple forms on a page.


The Google ReCaptcha SDK has been updated to the latest version.


The code for this Extra is open-source and managed in Github. Please submit issues and bug reports there.

Have fun (Re)captcha-ing spam bots!