This page describes methods of the reCAPTCHA JavaScript API and their configuration parameters that you can use to render the web pages with a reCAPTCHA key (site key).
reCAPTCHA JavaScript API methods
This section describes the syntax and parameters of reCAPTCHA JavaScript API methods.
grecaptcha.enterprise.render
Renders the container as a reCAPTCHA widget and returns the ID of the newly created widget.
Syntax
grecaptcha.enterprise.render(container: string | HTMLelement, parameters: Object): number
Method Parameters
Parameter | Description |
---|---|
container | The HTML element to render the reCAPTCHA widget. Specify either the ID of the container (string) or the DOM element itself. |
parameters |
An object containing parameters as key=value pairs, for example,
See Attributes and parameters for details about each configurable parameter. |
Return value
Returns the ID of the newly created widget.
grecaptcha.enterprise.reset
Resets the reCAPTCHA widget.
Syntax
grecaptcha.enterprise.reset(widget_id: number): void
Parameters
Parameter | Description |
---|---|
widget_id | Optional. Widget ID returned from grecaptcha.enterprise.render() . If not
specified, it defaults to the ID of the first widget that was created.
|
Return value
Does not return a value.
grecaptcha.enterprise.execute
Programmatically invokes the reCAPTCHA verification.
Syntax
grecaptcha.enterprise.execute(widget_id: number): Promise<string>
grecaptcha.enterprise.execute(sitekey: string, action: Object): Promise<string>
Parameters
Parameter | Description |
---|---|
widget_id | Optional. Widget ID returned from grecaptcha.enterprise.render() .
If not specified, it defaults to the ID of the first widget that was created. |
sitekey |
Specify the reCAPTCHA site key to be protected. |
action | An object with a single key=value pair, where the value for
action key specifies the action name associated with the
protected element.
For example: |
Return value
If successful, returns a Promise object containing the token if successful.
grecaptcha.enterprise.ready
Runs your function when the reCAPTCHA JavaScript library loads.
Syntax
grecaptcha.enterprise.ready(callback: function): void
Parameters
Parameter | Description |
---|---|
callback | The function to call when the reCAPTCHA library finishes loading. |
Return value
Does not return a value.
grecaptcha.enterprise.getResponse
Gets the response for the reCAPTCHA widget.
Syntax
grecaptcha.enterprise.getResponse(widget_id: number): string
Parameters
Parameter | Description |
---|---|
widget_id | Optional. Widget ID returned from grecaptcha.enterprise.render() . If
not specified, it defaults to the ID of the first widget that was created.
|
Return value
Gets the response of the reCAPTCHA widget. It can be either a string with the
token created by grecaptcha.enterprise.execute()
or an empty
string if the token has not yet been created.
Configuration
This section describes the JavaScript resource parameters and the parameters
used by grecaptcha.enterprise.render()
and attributes of the
g-recaptcha
widget.
JavaScript resource (enterprise.js) parameters
The following table lists the parameters of the JavaScript resource (enterprise.js
)
that you must include when using reCAPTCHA.
For more information about using these parameters, see the examples in Rendering the reCAPTCHA widget on the frontend.
Parameter | Value | Description |
---|---|---|
onload |
callback | Optional. The name of your callback function to be executed after all the dependencies have loaded. |
render
|
onload |
Optional, default value. Renders the widget in the first |
explicit
|
Optional. Does not render the widget automatically. You need to call
|
|
siteKey |
When used with score-based site keys, this parameter is not optional. The value siteKey specifies the score-based site key associated. |
|
hl |
See language codes. | Optional. Forces the widget to render in a specific language. Auto-detects the user's language if unspecified. |
g-recaptcha tag attributes and grecaptcha.enterprise.render() parameters
The following table lists the g-recaptcha
tag attributes and the corresponding
grecaptcha.enterprise.render()
parameters.
g-recaptcha tag attribute |
grecaptcha.enterprise.render() parameter |
Allowed values | Default | Description |
---|---|---|---|---|
data-sitekey |
sitekey |
reCAPTCHA Key. | ||
data-badge |
badge |
bottomright , bottomleft , inline
|
bottomright |
Optional. Reposition the reCAPTCHA badge. inline lets you position it with CSS. |
data-action |
action |
Optional. String describing current action. | ||
data-theme |
theme |
dark , light |
light |
Optional. The color theme of the widget. |
data-size |
size |
compact , normal |
normal |
Optional. The size of the widget. |
data-tabindex |
tabindex |
Integer | 0 | Optional. The tabindex of the widget and challenge. If other elements in your page use tabindex, it should be set to make user navigation easier. |
data-callback |
callback |
String | N/A | Optional. The name of your callback function, executed when the user
submits a successful response. The g-recaptcha-response
token is passed to your callback. |
data-expired-callback |
expired-callback |
String | N/A | Optional. The name of your callback function, executed when the reCAPTCHA response expires and the user needs to re-verify. |
data-error-callback |
error-callback |
String | N/A | Optional. The name of your callback function, executed when reCAPTCHA encounters an error (usually network connectivity) and cannot continue until connectivity is restored. The callback does not receive any arguments containing error details. If you specify a function here, you are responsible for informing the user that they should retry. |