FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

Recaptcha Google v2.0

v2.3.0 Public

ColdBox ReCAPTCHA Google v2.0 Module

This module contains helpers for using Google's ReCAPTCHA API.

reCAPTCHA is a free service that protects your site from spam and abuse. It uses advanced risk analysis techniques to tell humans and bots apart. With the 2.0 API, a significant number of your valid human users will pass the reCAPTCHA challenge without having to solve a CAPTCHA. reCAPTCHA comes in the form of a widget that you can easily add to your blog, forum, registration form, etc.


Apache License, Version 2.0.


  • Lucee 5+
  • ColdFusion 11+
  • ColdBox 5+


Just drop into your modules folder or use the CommandBox to install

box install recaptcha2



Get an API key pair at and add the following settings to your Coldbox.cfc under a recaptcha structure within the moduleSettings structure:

moduleSettings = {
	// recaptcha settings
	recaptcha = {
    	secretKey 	= "Secret key",
    	publickey 	= "Site key",

Rendering Recaptcha

In any form you wish to add the reCaptcha widget use the following:

<div class="form-group">
		size = "normal" // normal or compact

The only argument the widget receives is the size of the captcha:

  • normal
  • compact


Validation can be done manually or using or custom validator that leverages the cbValidation module (

Custom Validator

In your handler for the post of the form, or in a model object you can then use the included Validator. Here is an example of using it in a model object:

this.constraints = {
	"body" 	: { required : true },
	"recaptcha" : { validator: "[email protected]" }

In the above example, your handler would just need to set the recaptcha property on the model object to the g-recaptcha-response value that is part of the form payload.

Manual Validation

There also is a [email protected] Wirebox mapping you can use to validate manually if you prefer to not use the cbvalidation integration. In your handler:

var recaptchaOK = getInstance( "[email protected]" ).isValid( rc[ "g-recaptcha-response" ] );

if ( !recaptchaOK ){
    writeOutput( "Prove you have a soul!" );

Dependencies (1)

Dev Dependencies (0)



  • Updates to readme for markdown fixes and more docs
  • ACF comptability
  • ColdBox 5 module settings upgrade
  • Standardization of names for keys
  • linting and editor configs
  • Test Harness, tests and env variables.


$ box install recaptcha2

No collaborators yet.
  • {{ getFullDate("Mar 17 2021 01:03 PM GMT") }}
  • {{ getFullDate("Mar 17 2021 01:03 PM GMT") }}
  • 4,244
  • 2,669
  • 8,428