Recaptcha plugin

Show and validate a Google reCAPTCHA v2

Use the Recaptcha3 plugin if you are using Google reCAPTCHA v3

Usage

To use it, you need to register a site and secret keys at reCaptcha admin page.

The following piece of code is the starting point to use the Recaptcha plugin:

<html>
    <head>
        <link rel="stylesheet" href="/vendors/@form-validation/umd/styles/index.min.css" />
    </head>
    <body>
        <form id="demoForm" method="POST">
            ...

            <!-- Prepare a container to show the captcha -->
            <div id="captchaContainer"></div>
        </form>

        <script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.3/es6-shim.min.js"></script>
        <script src="/vendors/@form-validation/umd/bundle/popular.min.js"></script>
        <script src="/vendors/@form-validation/umd/plugin-recaptcha/index.min.js"></script>

        <script>
            document.addEventListener('DOMContentLoaded', function(e) {
                FormValidation.formValidation(
                    document.getElementById('demoForm'),
                    {
                        fields: {
                            ...
                        },
                        plugins: {
                            ...,
                            recaptcha: new FormValidation.plugins.Recaptcha({
                                element: 'captchaContainer',
                                language: ...,
                                message: ...,
                                siteKey: ...,
                                theme: ...,
                            }),
                        },
                    }
                );
            });
        </script>
    </body>
</html>

The sample code above assumes that the FormValidation files are placed inside the vendors directory. You might need to change the path depending on where you place them on the server.

Options

Option	Type	Description
`backendVerificationUrl`	`String`	The URL of your back-end that verifies the captcha via reCAPTCHA API
`badge`	`String`	The position of invisible reCAPTCHA

It can be one of

bottomright (the default value)
bottomleft
inline

Use this option along with size: 'invisible' for invisible reCAPTCHA

Option	Type	Description
`element` *	`String`	The ID of element showing the captcha
`language`	`String`	The language code defined by reCAPTCHA
`message` *	`String`	The invalid message that will be shown in case the captcha is not valid
`siteKey` *	`String`	The site key provided by Google
`size`	`String`	The size of reCAPTCHA widget

It can be one of

normal (the default value)
compact
invisible

The first two options are available for the reCAPTCHA widget. The last one has to be used if you want to use invisible reCAPTCHA.

Option	Type	Description
`theme`	`String`	The theme name provided by Google

It can be one of

light (the default value)
dark

Using the npm packages

If you are using a bundler such as Webpack, Rollup, Parcel or Vite, etc., to bundle your application, then it's recommended to use the FormValidation NPM packages.

Install the packages:

$ npm install @form-validation/bundle
$ npm install @form-validation/plugin-recaptcha

Import and use the Recaptcha plugin:

import { formValidation } from '@form-validation/bundle/popular';
import { Recaptcha } from '@form-validation/plugin-recaptcha';

formValidation(
    document.getElementById('demoForm'),
    {
        fields: {
            ...
        },
        plugins: {
            recaptcha: new Recaptcha({
                ...
            }),
            ...
        },
    }
);

reCAPTCHA widget

The following form shows a reCAPTCHA widget.

reCAPTCHA widget

Invisible reCAPTCHA

The following form shows an invisible reCAPTCHA. In order to use it properly, remember to set the size: 'invisible' option.

Invisible reCAPTCHA

Back-end verification

If you want to take more steps of checking if the visitor on your site isn't a robot, then let's verify the captcha on the back-end side. You need to point the backendVerificationUrl option to your back-end URL:

FormValidation.formValidation(
    document.getElementById('demoForm'),
    {
        fields: {
            ...
        },
        plugins: {
            ...
            recaptcha: new FormValidation.plugins.Recaptcha({
                backendVerificationUrl: '/path/to/your/back-end/',
            }),
        },
    }
);

When that option is enabled, the plugin will send an Ajax request with the value for g-recaptcha-response parameter. With the value of captcha and the reCAPTCHA secret key, you can connect to reCAPTCGA verification URL to verify the captcha.

In order to inform user in case the captcha is valid or invalid, the back-end has to return a JSON encoded version of

{
    "success": "true"
}
// or
{
    "success": "false"
}

The following code demonstrates how to do it in PHP, but you can do it with your favorite language.

<?php
// Replace it with your reCAPTCHA secret key
$secretKey = '...';

// See https://developers.google.com/recaptcha/docs/verify#api-request
$fields = array(
    'secret'   => $secretKey,
    'response' => $_POST['g-recaptcha-response']
);

$postVars = '';
$sep = '';
foreach ($fields as $key => $value) {
    $postVars .= $sep . urlencode($key) . '=' . urlencode($value);
    $sep = '&';
}

$ch = curl_init();

curl_setopt($ch,CURLOPT_URL, 'https://www.google.com/recaptcha/api/siteverify');
curl_setopt($ch,CURLOPT_POST, count($fields));
curl_setopt($ch,CURLOPT_POSTFIELDS, $postVars);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);

curl_close($ch);

header('Content-Type: application/json');
echo $result;

Changelog

v2.4.0

The plugin can be enabled or disabled using the enablePlugin and disablePlugin methods

v2.1.0

The plugin doesn't clear the loaded callback after uninstalling

v2.0.0

Add the npm package

v1.7.0

Fix an issue that the plugin sends the back-end verification request twice

v1.5.0

Hide the icon for the invisible reCAPTCHA.

v1.4.0

In the previous version, the Recaptcha plugin doesn't hide the error message and error icon when user click the captcha checkbox. The error icon disappears when the captcha is expired. This version fixes that.

v1.1.0

Added backendVerificationUrl option to support back-end verification
Removed the timeout option. The captcha expiration will be handled by the plugin automatically
Removed unused stoken option
Supported invisible reCAPTCHA

v1.0.0

First release

Pure plugin Recaptcha3 plugin