easycaptchajs
Advanced tools
Readme
EasyCaptchaJS is a lightweight and user-friendly jQuery/JS library that simplifies the integration of Google reCAPTCHA API into web pages. With EasyCaptchaJS, developers can effortlessly add the security and anti-bot protection of reCAPTCHA to their web applications, enhancing their overall security and user experience.
To use the EasyCaptchaJS jQuery Plugin, you need the following dependencies:
To use the EasyCaptchaJS Plugin in your project, you can include the necessary files via npm, CDN or by downloading the files locally.
You can install EasyCaptchaJS via npm:
npm install easycaptchajs
You can also include EasyCaptchaJS directly from a CDN by adding the following script tag to your HTML file:
<script src="https://cdn.jsdelivr.net/gh/HichemTab-tech/EasyCaptchaJS@1.2.1/dist/easycaptcha.min.js"></script>
If you prefer to host the library locally, you can download the latest release from the source code and include it in your project:
<script src="path/to/easycaptcha.min.js"></script>
EasyCaptchaJS can be easily initialized on target elements using jQuery. The library supports two methods of providing options:
<div id="targetElement"></div>
const options = {
ReCAPTCHA_API_KEY_CLIENT: 'YOUR_RECAPTCHA_SITE_KEY',
// Add other options here
};
// Initialize EasyCaptchaJS with options
$('YOUR_TARGET_ELEMENT_SELECTOR').EasyCaptcha(options);
<div data-recaptcha-apikey="GOOGLE_RECAPTCHA_API_KEY_CLIENT"
data-theme="dark"
data-okbtn-selector="#submitBtn"
data-required-msg-example-selector="#errorMsgExample"
data-loading-msg-example-selector="#loadingMsgExample"
data-error-msg-example-selector="#errorMsgExample"
></div>
$('YOUR_TARGET_ELEMENT_SELECTOR').EasyCaptcha();
you can skip initializing the EasyCaptchaJS by adding the data-auto-easycaptcha to the targetElement so the library will render everything automatically after the page load with any js code.
in this case you need to add the GOOGLE_RECAPTCHA_API_KEY_CLIENT in a meta tag in <head> like the following example :
<head>
<title>EasyCaptchaJs Demo</title>
...
<meta name="ReCAPTCHA_API_KEY_CLIENT" content="GOOGLE_RECAPTCHA_API_KEY_CLIENT">
</head>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>EasyCaptchaJs - Example 1</title>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM" crossorigin="anonymous">
<meta name="ReCAPTCHA_API_KEY_CLIENT" content="YOUR_RECAPTCHA_SITE_KEY">
</head>
<body>
<form>
<div class="container">
<h1>EasyCaptchaJs</h1>
<label class="label">Hi</label>
<div class="form-group">
<div class="captchaTarget" data-auto-easycaptcha data-okbtn-selector="#ok"></div>
</div>
<div class="form-group">
<button type="button" class="btn btn-primary" id="ok">OK</button>
</div>
</div>
</form>
<script src="https://code.jquery.com/jquery-3.7.0.min.js" integrity="sha256-2Pmvv0kuTBOenSvLm6bvfBSSHrUJ+3A7x6P5Ebd07/g=" crossorigin="anonymous"></script>
<script src="dist/easycaptcha.js"></script>
</body>
</html>
Replace 'YOUR_RECAPTCHA_SITE_KEY' with your actual Google reCAPTCHA site key.
Save the HTML file and open it in your web browser.
The form will display a Google reCAPTCHA checkbox. When users complete the reCAPTCHA verification, the "OK" button will become enabled, allowing them to proceed with form submission.
This example demonstrates the auto-rendering capability of EasyCaptchaJs using data attributes. By adding the data-auto-easycaptcha attribute to the target element, the library automatically renders the Google reCAPTCHA checkbox without the need for additional JavaScript initialization.
"captchaTarget" due to the presence of the data-auto-easycaptcha attribute. The library handles the integration of the reCAPTCHA API script and initialization process.data-okbtn-selector attribute is used to associate the "OK" button with EasyCaptchaJs. When the reCAPTCHA is verified, the button becomes clickable, allowing users to proceed with form submission, also when the verification expires or fails the button will be disabled again.This example showcases the simplicity of adding Google reCAPTCHA to a form with just a few data attributes. It provides a user-friendly approach to ensure that only human interactions are allowed in the form submission process.
This example demonstrates how to initialize EasyCaptchaJs using the options object and target a specific element by its ID for reCAPTCHA integration.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>EasyCaptchaJs - Example 2</title>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM" crossorigin="anonymous">
<meta name="ReCAPTCHA_API_KEY_CLIENT" content="YOUR_RECAPTCHA_SITE_KEY">
</head>
<body>
<form>
<div class="container">
<h1>EasyCaptchaJs - Example 2</h1>
<label class="label">Hi</label>
<div class="form-group">
<div id="myCaptcha"></div>
</div>
<div class="form-group">
<button type="button" class="btn btn-primary" id="okBtn">OK</button>
</div>
</div>
</form>
<script src="https://code.jquery.com/jquery-3.7.0.min.js" integrity="sha256-2Pmvv0kuTBOenSvLm6bvfBSSHrUJ+3A7x6P5Ebd07/g=" crossorigin="anonymous"></script>
<script src="dist/easycaptcha.js"></script>
<script>
// JavaScript
const options = {
ReCAPTCHA_API_KEY_CLIENT: 'YOUR_RECAPTCHA_SITE_KEY',
ReCaptchaSubmit: {
success: () => {
console.log('reCAPTCHA verification successful!');
},
failed: () => {
console.log('reCAPTCHA verification failed!');
},
expired: () => {
console.log('reCAPTCHA verification expired!');
},
},
autoVerification: {
okBtn: "#okBtn",
requiredMsg: "<div class='alert alert-danger'>Please verify that you are not a robot.</div>",
},
apiScriptLoading: {
error: () => {
console.log('Error while loading API script.');
},
},
};
// Initialize EasyCaptchaJs with options object and target element by ID
$('#myCaptcha').EasyCaptcha(options);
</script>
</body>
</html>
In this example, we will showcase how to initialize EasyCaptchaJs on multiple targets using the shared class name for initialization. Additionally, we will customize messages in two ways: using the options object and using attributes with predefined elements.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>EasyCaptchaJs - Example 3</title>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM" crossorigin="anonymous">
<meta name="ReCAPTCHA_API_KEY_CLIENT" content="YOUR_RECAPTCHA_SITE_KEY">
</head>
<body>
<form>
<div class="container">
<h1>EasyCaptchaJs - Example 3</h1>
<div class="form-group">
<div class="captchaTarget" data-okbtn-selector="#okBtn1"></div>
</div>
<div class="form-group">
<button type="button" class="btn btn-primary" id="okBtn1">OK</button>
</div>
<div class="form-group">
<div class="captchaTarget" data-okbtn-selector="#okBtn2"
data-required-msg-example-selector="#msg2"></div>
</div>
<div class="form-group">
<button type="button" class="btn btn-primary" id="okBtn2">OK</button>
</div>
</div>
<div class='alert alert-danger hidden' id="msg1">Please check the box above!</div>
<div class='alert alert-danger hidden' id="msg2">Don't forget to verify!</div>
</form>
<script src="https://code.jquery.com/jquery-3.7.0.min.js" integrity="sha256-2Pmvv0kuTBOenSvLm6bvfBSSHrUJ+3A7x6P5Ebd07/g=" crossorigin="anonymous"></script>
<script src="dist/easycaptcha.js"></script>
</body>
</html>
// JavaScript
const options = {
ReCAPTCHA_API_KEY_CLIENT: 'YOUR_RECAPTCHA_SITE_KEY',
ReCaptchaSubmit: {
success: () => {
console.log('reCAPTCHA verification successful!');
},
failed: () => {
console.log('reCAPTCHA verification failed!');
},
expired: () => {
console.log('reCAPTCHA verification expired!');
},
},
autoVerification: {
requiredMsg: $("#msg1"),
},
apiScriptLoading: {
loadingMsg: '<div class="spinner-border text-warning" role="status"></div>',
error: () => {
console.log('Error while loading API script.');
},
errorMsg: "<div class='alert alert-danger'>Custom Error while loading API Script. <b class='retry-load-api-script clickable'>retry</b></div>",
},
};
// Initialize EasyCaptchaJs on multiple targets with the shared class name "captchaTarget"
$('.captchaTarget').EasyCaptcha(options);
Note: the attributes data overrider the options object data.
In this example, two captcha targets are selected using the shared class name "captchaTarget." The first captcha target uses customized messages directly through the options object, while the second captcha target utilizes predefined elements with customized messages using attributes.
The customized messages enhance the user experience and provide developers with flexible options to tailor the EasyCaptchaJs behavior according to their specific requirements.
| Option | Type | Default | Description |
|---|---|---|---|
ReCAPTCHA_API_KEY_CLIENT | String | null | The Google reCAPTCHA site key to be used for verification. Replace null with your actual Google reCAPTCHA site key. |
ReCaptchaSubmit.success | Function | () => {} | The function to be executed when the reCAPTCHA verification is successful. |
ReCaptchaSubmit.failed | Function | (error) => {} | The function to be executed when the reCAPTCHA verification fails. |
ReCaptchaSubmit.expired | Function | () => {} | The function to be executed when the reCAPTCHA verification expires. |
autoVerification.okBtn | String | Jquery | null | The selector of the "OK" button that should be enabled or disabled based on the reCAPTCHA verification state. Set it to null if not required. |
autoVerification.requiredMsg | String | Jquery | '<div class='alert alert-danger'>Please verify that you are not a robot.</div>' | The message to be displayed when the user has not completed the reCAPTCHA verification. |
apiScriptLoading.loadingMsg | String | Jquery | '<div class="spinner-border text-primary" role="status"></div>' | The loading message displayed while the API script is being loaded. |
apiScriptLoading.error | Function | () => {} | The function to be executed if an error occurs while loading the API script. |
apiScriptLoading.errorMsg | String | Jquery | '<div class='alert alert-danger'>Error while loading Api Script. <b class='retry-load-api-script clickable'>retry</b></div>' | The error message to be displayed when there is an error loading the API script. It includes a "retry" button for users to attempt reloading. |
theme | String | 'light' | The theme to be used for the Google reCAPTCHA widget. Supported values are 'light' and 'dark'. |
failure | Function | (error) => { console.error(error); } | The function to be executed when any failure occurs within EasyCaptchaJs. It is mainly used for error logging and handling. |
Here's a preview of default options :
let options = {
ReCAPTCHA_API_KEY_CLIENT: null,
ReCaptchaSubmit: {
success: () => {
},
failed: () => {
},
expired: () => {
},
},
autoVerification: {
okBtn: null,
requiredMsg: "<div class='alert alert-danger'>Please verify that you are not a robot.</div>",
},
apiScriptLoading: {
loadingMsg: '<div class="spinner-border text-primary" role="status"></div>',
error: () => {
},
errorMsg: "<div class='alert alert-danger'>Error while loading Api Script. <b class='retry-load-api-script clickable'>retry</b></div>",
},
theme: 'light',
failure: (error) => {
console.error(error);
}
};
| Data Attribute | Description | Example Usage |
|---|---|---|
data-okbtn-selector | The selector of the "OK" button that should be enabled or disabled based on the reCAPTCHA verification state. remove it if not required. | data-okbtn-selector="#myOKButton" |
data-recaptcha-apikey | The Google reCAPTCHA site key to be used for verification. | data-recaptcha-apikey="YOUR_RECAPTCHA_SITE_KEY" |
data-required-msg-example-selector | The selector of an example element that contains the custom message to be displayed when the user has not completed the reCAPTCHA verification. It should have class 'hidden' initially. | data-required-msg-example-selector="#msg1" |
data-loading-msg-example-selector | The selector of an example element that contains the custom loading message to be displayed while the API script is being loaded. It should have class 'hidden' initially. | data-loading-msg-example-selector="#loadingMsgExample" |
data-error-msg-example-selector | The selector of an example element that contains the custom error message to be displayed when there is an error loading the API script. It should have class 'hidden' initially. The error message should include a clickable element with class 'retry-load-api-script'. | data-error-msg-example-selector="#errorMsgExample" |
data-theme | The theme to be used for the Google reCAPTCHA widget. Supported values are 'light' and 'dark'. | data-theme="dark" |
data-auto-easycatcha | If you add this attribute you don't need to initialize the library with js, it will be initialized automatically right after the page loads | data-auto-easycaptcha |
EasyCaptchaJs provides some methods that can be called on the EasyCaptcha elements using the $().EasyCaptcha('methodName') syntax. Each method performs a specific action and returns the results in a structured format. Here are the available methods and their return types:
| Property | Type | Description |
|---|---|---|
parentElement | JQuery | The parent element of the EasyCaptcha checkbox. |
verified | Boolean | A boolean indicating whether the reCAPTCHA checkbox has been verified. |
| Property | Type | Description |
|---|---|---|
parentElement | JQuery | The parent element of the EasyCaptcha checkbox. |
token | String | The reCAPTCHA response token as a string. |
'reset' : This method is used to reset the reCAPTCHA checkbox. It takes no arguments and does not return anything.
'destroy' : This method is used to destroy the EasyCaptcha elements and remove their associated data. It does not return anything.
Note: The library function EasyCaptcha at the end returns either the array of results if there are multiple results, or a single result object if there is only one result. If no results are available, it returns null.
Here's a Demo example :
Contributions are always welcome!
If you have any ideas, improvements, or bug fixes, please open an issue or submit a pull request.
FAQs
EasyCaptchaJS is a lightweight and user-friendly jQuery/JS library that simplifies the integration of Google reCAPTCHA API into web pages. With EasyCaptchaJS, developers can effortlessly add the security and anti-bot protection of Google reCAPTCHA to thei
The npm package easycaptchajs receives a total of 23 weekly downloads. As such, easycaptchajs popularity was classified as not popular.
We found that easycaptchajs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.