The reCAPTCHA element allows you to present a challenge-response test to site visitors to determine whether they are human or a bot.
Use the reCAPTCHA element to verify that site visitors are human before allowing them to perform restricted operations such as data submission, login, or accessing private content.
The following outlines a typical reCAPTCHA validation lifecycle:
Getting Started
Videos
Examples
Forumtoken is generated. Use the onVerified() event handler to enable the disabled clickable element.onError() event handler to reset() the reCAPTCHA and ask the visitor to redo the challenge. Return to Step 1.authorize() with the generated token.onTimeout() event handler to disable the clickable trigger. Return to Step 1.authorize() checks whether the reCAPTCHA token is valid. One of the following occurs:
Important: To ensure complete protection, you must include backend authorization as a mandatory step of the reCAPTCHA validation lifecycle.
For more information on working with your reCAPTCHA element, click here.
insert() or save()).PROPERTIES
FUNCTIONS
Adds an event handler that runs when the mouse pointer is moved onto the element.
Adds an event handler that runs when the mouse pointer is moved off of the element.
Adds an event handler that runs when an element is displayed in the viewable part of the current window.
Adds an event handler that runs when an element is no longer displayed in the viewable part of the current window.
If global is true, the element appears on all pages.
If global is false, the element only appears on the current page.
get global(): boolean
let isGlobal = $w("#myElement").global; // falseThe ID is the element's unique identifier. It is used when selecting
elements using the $w() function.
An element's id is set in the Editor using the Properties panel.
get id(): string
let myId = $w("#myElement").id; // "myElement"get parent(): Node
let parentElement = $w("#myElement").parent;
let parentId = parentElement.id; // "page1"get rendered(): boolean
let isRendered = $w("#myElement").rendered; // trueWhen a site visitor successfully completes a reCAPTCHA challenge, a reCAPTCHA token
is generated. The token is used for backend authorization.
Prior to completing the reCAPTCHA challenge and following timeout, the token returns undefined.
get token(): string
let myToken = $w("#myCaptcha").token;
// "01ABCDeFG23hijKlmn4...OPQ5r6stuvWXy"This example demonstrates how to use reCAPTCHA to protect a data insertion. We use a text input for the data, a reCAPTCHA element, and a submit button. The submit button is disabled until the site visitor completes the reCAPTCHA challenge and the reCAPTCHA is verified. Clicking the submit button triggers backend authorization of the token. If authorization is successful, the data is inserted into the collection.
/************************************
* backend code - submitHandler.jsw *
************************************/
import wixCaptcha from 'wix-captcha-backend';
import wixData from 'wix-data';
// Authorize token and insert data
export function processSubmission(submitRequestData) {
return wixCaptcha.authorize(submitRequestData.token)
.then (() => {
return wixData.insert("MyCollection", submitRequestData.data);
});
}
/********************
* client-side code *
********************/
import {processSubmission} from 'backend/submitHandler';
$w.onReady(function () {
// When user clicks submit button
$w("#submitDataButton").onClick(() =>
let submitRequestData = {
token: $w("#myCaptcha").token,
data: $w("#myInput").value,
}
processSubmission(submitRequestData) // Call backend function
.then( () => {
$w("#myCaptcha").reset();
$w("#submitDataButton").disable();
$w("#messageText").text = "Data successfully submitted";
$w("#messageText").show();
})
.catch( () => {
$w("#myCaptcha").reset();
$w("#submitDataButton").disable();
$w("#messageText").text = "Something went wrong. Redo the reCAPTCHA challenge.";
$w("#messageText").show();
})
}
// Error handler
$w("#myCaptcha").onError(() => {
$w("#messageText").text = "Something went wrong. Redo the reCAPTCHA challenge.";
$w("#messageText").show();
})
// Verification handler
$w("#myCaptcha").onVerified(() => {
$w("#submitDataButton").enable();
$w("#messageText").hide();
})
// Timeout handler
$w("#myCaptcha").onTimeout(() => {
$w("#submitDataButton").disable();
})
});
let myType = $w("#myElement").type; // "$w.Type"The blur() function removes focus from the element and fires a blur
event.
The blur event handlers set on this element by the onBlur( )
function or in the Editor are called.
Removing focus through a call to this function is equivalent to a user clicking on another element or tabbing out of the element manually.
If blur() is called on an element that is not in focus, it has no effect.
The element in focus remains in focus and the onBlur event handlers
are not called.
function blur(): void$w("#myElement").blur();The focus() function places focus on the element and fires a focus
event.
The focus event handlers set on this element by the onFocus( )
function or in the Editor are called.
Receiving focus through a call to this function is equivalent to a user clicking on or tabbing to the element manually.
function focus(): void$w("#myElement").focus();An element loses focus (blurs) through user actions, such as clicking and tabbing, or programmatically, using the blur( ) function.
onBlur() has no effect when applied to RadioButtonGroup elements.
Deprecation note: The $w parameter of event handlers is being deprecated. To get
a scoped selector for working with elements in repeater items, use the $w.at() function
and pass it the context property of the event parameter: $item = $w.at(event.context). To learn more, see
here.
function onBlur(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): voidThe name of the function or the function expression to run when the element losed focus.
$w("#myElement").onBlur( (event) => {
let targetId = event.target.id; // "myElement"
});The onError() function allows you to perform actions when the reCAPTCHA element on the client side
has a communication error with the reCAPTCHA provider.
If an error occurs, the reCAPTCHA element automatically resets. You can ask the user to redo the challenge.
function onError(handler: ErrorHandler): void
callback ErrorHandler(): voidThe name of the function or the function expression to run when an error occurs.
$w("#myCaptcha").onError(() => {
$w("#messageText").text = "Something went wrong. Redo the reCAPTCHA challenge.";
$w("#messageText").show();
})An element receives focus through user actions, such as clicking and tabbing, or programmatically, using the focus( ) function.
onFocus() has no effect when applied to RadioButtonGroup elements.
Deprecation note: The $w parameter of event handlers is being deprecated. To get
a scoped selector for working with elements in repeater items, use the $w.at() function
and pass it the context property of the event parameter: $item = $w.at(event.context). To learn more, see
here.
function onFocus(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): voidThe name of the function or the function expression to run when the element receives focus.
$w("#myElement").onFocus( (event) => {
let targetId = event.target.id; // "myElement"
});Adds an event handler that runs when the mouse pointer is moved onto the element.
Deprecation note: The $w parameter of event handlers is being deprecated. To get
a scoped selector for working with elements in repeater items, use the $w.at() function
and pass it the context property of the event parameter: $item = $w.at(event.context). To learn more, see
here.
function onMouseIn(handler: MouseEventHandler): Element
callback MouseEventHandler(event: MouseEvent, $w: $w): voidThe name of the function or the function expression to run when the mouse pointer is moved onto the element.
$w("#myElement").onMouseIn( (event) => {
let clientX = event.clientX; // 362
let clientY = event.clientY; // 244
let offsetX = event.offsetX; // 10
let offsetY = event.offsetY; // 12
let pageX = event.pageX; // 362
let pageY = event.pageY; // 376
let screenX = event.screenX; // 3897
let screenY = event.screenY; // 362
} );Adds an event handler that runs when the mouse pointer is moved off of the element.
Deprecation note: The $w parameter of event handlers is being deprecated. To get
a scoped selector for working with elements in repeater items, use the $w.at() function
and pass it the context property of the event parameter: $item = $w.at(event.context). To learn more, see
here.
function onMouseOut(handler: MouseEventHandler): Element
callback MouseEventHandler(event: MouseEvent, $w: $w): voidThe name of the function or the function expression to run when the mouse pointer is moved off of the element.
$w("#myElement").onMouseOut( (event) => {
let clientX = event.clientX; // 362
let clientY = event.clientY; // 244
let offsetX = event.offsetX; // 10
let offsetY = event.offsetY; // 12
let pageX = event.pageX; // 362
let pageY = event.pageY; // 376
let screenX = event.screenX; // 3897
let screenY = event.screenY; // 362
} );The onTimeout() function allows you to perform actions when a reCAPTCHA timeout occurs.
When a site visitor completes a reCAPTCHA challenge, a token is
generated. If 120 seconds pass without backend authorization,
the token expires and onTimeout() is called.
When a timeout occurs, the reCAPTCHA automatically resets and displays a message asking the site visitor to redo the challenge. If you enabled the clickable element for triggering a restricted operation when the reCAPTCHA was verified, disable it.
function onTimeout(handler: TimeoutHandler): void
callback TimeoutHandler(): voidThe name of the function or the function expression to run when a reCAPTCHA timeout occurs.
$w("#myCaptcha").onTimeout(() => {
$w("#signupButton").disable();
})Once the reCAPTCHA challenge has been successfully completed by the user, the onVerified
callback is triggered and a reCAPTCHA token is generated.
If the clickable element for triggering the submit or another restricted operation was disabled, enable it.
function onVerified(handler: VerifiedHandler): void
callback VerifiedHandler(): Promise<void>The name of the function or the function expression to run when the reCAPTCHA is verified.
$w("#myCaptcha").onVerified(() => {
$w("#signupButton").enable();
let myToken = $w("#myCaptcha").token;
})This example demonstrates how to use reCAPTCHA to protect a data insertion. We use a text input for the data, a reCAPTCHA element, and a submit button. The submit button is disabled until the site visitor completes the reCAPTCHA challenge and the reCAPTCHA is verified. Clicking the submit button triggers backend authorization of the token. If authorization is successful, the data is inserted into the collection.
/************************************
* backend code - submitHandler.jsw *
************************************/
import wixCaptcha from 'wix-captcha-backend';
import wixData from 'wix-data';
// Authorize token and insert data
export function processSubmission(submitRequestData) {
return wixCaptcha.authorize(submitRequestData.token)
.then (() => {
return wixData.insert("MyCollection", submitRequestData.data);
});
}
/********************
* client-side code *
********************/
import {processSubmission} from 'backend/submitHandler';
$w.onReady(function () {
// When user clicks submit button
$w("#submitDataButton").onClick(() =>
let submitRequestData = {
token: $w("#myCaptcha").token,
data: $w("#myInput").value,
}
processSubmission(submitRequestData) // Call backend function
.then( () => {
$w("#myCaptcha").reset();
$w("#submitDataButton").disable();
$w("#messageText").text = "Data successfully submitted";
$w("#messageText").show();
})
.catch( () => {
$w("#myCaptcha").reset();
$w("#submitDataButton").disable();
$w("#messageText").text = "Something went wrong. Redo the reCAPTCHA challenge.";
$w("#messageText").show();
})
}
// Error handler
$w("#myCaptcha").onError(() => {
$w("#messageText").text = "Something went wrong. Redo the reCAPTCHA challenge.";
$w("#messageText").show();
})
// Verification handler
$w("#myCaptcha").onVerified(() => {
$w("#submitDataButton").enable();
$w("#messageText").hide();
})
// Timeout handler
$w("#myCaptcha").onTimeout(() => {
$w("#submitDataButton").disable();
})
});
Adds an event handler that runs when an element is displayed in the viewable part of the current window.
An element enters the viewport when the page is scrolled to show any
part of the element. An element also enters the viewport if it was
hidden or collapsed
and is then shown or expanded in the viewable part of the current window. onViewportEnter()
is not fired for hidden or collapsed
elements even if they are scrolled into view.
Deprecation note: The $w parameter of event handlers is being deprecated. To get
a scoped selector for working with elements in repeater items, use the $w.at() function
and pass it the context property of the event parameter: $item = $w.at(event.context). To learn more, see
here.
function onViewportEnter(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): voidThe name of the function or the function expression to run when the element enters the viewport.
$w("#myElement").onViewportEnter( (event) => {
let targetId = event.target.id; // "myElement"
});Adds an event handler that runs when an element is no longer displayed in the viewable part of the current window.
An element leaves the viewport when the page is scrolled so that the
element is completely out of view. An element also leaves the viewport
if it was shown or expanded and is then hidden
or collapsed from the viewable part
of the current window. onViewportLeave()
is not fired for hidden or collapsed
elements even if they are scrolled out of view.
Deprecation note: The $w parameter of event handlers is being deprecated. To get
a scoped selector for working with elements in repeater items, use the $w.at() function
and pass it the context property of the event parameter: $item = $w.at(event.context). To learn more, see
here.
function onViewportLeave(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): voidThe name of the function or the function expression to run when the element leaves the viewport.
$w("#myElement").onViewportLeave( (event) => {
let targetId = event.target.id; // "myElement"
});reset() the reCAPTCHA when there is a reCAPTCHA error. Also use reset()
when the operation restricted by the reCAPTCHA element is successfully completed
to enable the reCAPTCHA for the next operation.
function reset(): Promise<void>$w("#myCaptcha").reset();This example demonstrates how to use reCAPTCHA to protect a data insertion. We use a text input for the data, a reCAPTCHA element, and a submit button. The submit button is disabled until the site visitor completes the reCAPTCHA challenge and the reCAPTCHA is verified. Clicking the submit button triggers backend authorization of the token. If authorization is successful, the data is inserted into the collection.
/************************************
* backend code - submitHandler.jsw *
************************************/
import wixCaptcha from 'wix-captcha-backend';
import wixData from 'wix-data';
// Authorize token and insert data
export function processSubmission(submitRequestData) {
return wixCaptcha.authorize(submitRequestData.token)
.then (() => {
return wixData.insert("MyCollection", submitRequestData.data);
});
}
/********************
* client-side code *
********************/
import {processSubmission} from 'backend/submitHandler';
$w.onReady(function () {
// When user clicks submit button
$w("#submitDataButton").onClick(() =>
let submitRequestData = {
token: $w("#myCaptcha").token,
data: $w("#myInput").value,
}
processSubmission(submitRequestData) // Call backend function
.then( () => {
$w("#myCaptcha").reset();
$w("#submitDataButton").disable();
$w("#messageText").text = "Data successfully submitted";
$w("#messageText").show();
})
.catch( () => {
$w("#myCaptcha").reset();
$w("#submitDataButton").disable();
$w("#messageText").text = "Something went wrong. Redo the reCAPTCHA challenge.";
$w("#messageText").show();
})
}
// Error handler
$w("#myCaptcha").onError(() => {
$w("#messageText").text = "Something went wrong. Redo the reCAPTCHA challenge.";
$w("#messageText").show();
})
// Verification handler
$w("#myCaptcha").onVerified(() => {
$w("#submitDataButton").enable();
$w("#messageText").hide();
})
// Timeout handler
$w("#myCaptcha").onTimeout(() => {
$w("#submitDataButton").disable();
})
});
The scrollTo() function returns a Promise that is resolved when the
animated scroll is complete and the element is now in view.
To scroll to a specific location on the page, see the wix-window
scrollTo() function.
Calling the scrollTo() function on an element in a repeated item that
is selected from the global scope causes
an error.
function scrollTo(): Promise<void>$w("#myElement").scrollTo();$w("#myElement").scrollTo()
.then( ( ) => {
console.log("Done with scroll");
} );