Invisible reCAPTCHA

This page explains how to enable and customize the invisible reCAPTCHA on your webpage.

To invoke the invisible reCAPTCHA, you can either:

See Configurations to learn how to customize the invisible reCAPTCHA. For example, you may want to specify the language or badge location.

See Verifying the user's response to check if the user successfully solved the CAPTCHA.

Automatically bind the challenge to a button

The easiest method for using the invisible reCAPTCHA widget on your page is to include the necessary JavaScript resource and add a few attributes to your html button. The necessary attributes are a class name 'g-recaptcha', your site key in the data-sitekey attribute, and the name of a JavaScript callback to handle completion of the captcha in the data-callback attribute.

<html>
  <head>
    <title>reCAPTCHA demo: Simple page</title>
     <script src="https://www.google.com/recaptcha/api.js" async defer></script>
     <script>
       function onSubmit(token) {
         document.getElementById("demo-form").submit();
       }
     </script>
  </head>
  <body>
    <form id='demo-form' action="?" method="POST">
      <button class="g-recaptcha" data-sitekey="your_site_key" data-callback='onSubmit'>Submit</button>
      <br/>
    </form>
  </body>
</html>

The script must be loaded using the HTTPS protocol and can be included from any point on the page without restriction.

Programmatically bind the challenge to a button or invoke the challenge.

Deferring the binding can be achieved by specifying your onload callback function and adding parameters to the JavaScript resource. This works the same as the normal reCAPTCHA challenge.

Programmatically invoke the challenge.

Invoking the reCAPTCHA verification programmatically can be achieved by rendering the challenge in a div with an attribute data-size='invisible' and programmatically calling execute.

  1. Create a div with data-size='invisible'.
        <div class="g-recaptcha"
              data-sitekey="your_site_key"
              data-callback="onSubmit"
              data-size="invisible">
        </div>
  2. Call grecaptcha.execute from a javascript method.
          grecaptcha.execute();
        
    When your callback is executed, you can call the grecaptcha.render method from the Javascript API.

    Note: your onload callback function must be defined before the reCAPTCHA API loads. To ensure there are no race conditions:

    • order your scripts with the callback first, and then reCAPTCHA
    • use the async and defer parameters in the script tags

Configuration

JavaScript resource (api.js) parameters

Parameter Value Description
onload Optional. The name of your callback function to be executed once all the dependencies have loaded.
render explicit
onload
Optional. Whether to render the widget explicitly. Defaults to onload, which will render the widget in the first g-recaptcha tag it finds.
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.render parameters

g-recaptcha tag attribute grecaptcha.render parameter Value Default Description
data-sitekey sitekey Your sitekey.
data-badge badge bottomright bottomleft inline bottomright Optional. Reposition the reCAPTCHA badge. 'inline' allows you to control the CSS.
data-type type audio image image Optional. The type of CAPTCHA to serve.
data-size size invisible Optional. Used to create an invisible widget bound to a div and programatically executed.
data-tabindex tabindex 0 Optional. The tabindex of the challenge. If other elements in your page use tabindex, it should be set to make user navigation easier.
data-callback callback Required. The name of your callback function to be executed when the user submits a successful CAPTCHA response. The user's response, g-recaptcha-response, will be the input for your callback function.

JavaScript API

Method Description
grecaptcha.render(
container,
parameters
inherit
)
Renders the container as a reCAPTCHA widget and returns the ID of the newly created widget.
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, {"sitekey": "your_site_key", "theme": "light"}. See grecaptcha.render parameters. inherit
  Use existing data-* attributes on the element if the coorsponding parameter is not specified. The values in parameter will take precedence over the attributes.
grecaptcha.execute(
opt_widget_id
)
Programatically invoke the reCAPTCHA check. Used if the invisible reCAPTCHA is on a div instead of a button.
opt_widget_id
  Optional widget ID, defaults to the first widget created if unspecified.
grecaptcha.reset(
opt_widget_id
)
Resets the reCAPTCHA widget.
opt_widget_id
  Optional widget ID, defaults to the first widget created if unspecified.
grecaptcha.getResponse(
opt_widget_id
)
Gets the response for the reCAPTCHA widget.
opt_widget_id
  Optional widget ID, defaults to the first widget created if unspecified.

Examples

Explicit rendering after an onload callback

<html>
  <head>
    <title>reCAPTCHA demo: Explicit render after an onload callback</title>
    <script type="text/javascript">
      
        var onSubmit = function(token) {
          console.log('success!');
        };

        var onloadCallback = function() {
          grecaptcha.render('submit', {
            'sitekey' : 'your_site_key',
            'callback' : onSubmit
          });
        };
    </script>
  </head>
  <body>
    <form action="?" method="POST">
      <input id='submit' type="submit" value="Submit">
    </form>
    <script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

Invoking the invisible reCAPTCHA challenge after client side validation.

<html>
<head>
<script>
  function onSubmit(token) {
    alert('thanks ' + document.getElementById('field').value);
  }

  function validate(event) {
    event.preventDefault();
    if (!document.getElementById('field').value) {
      alert("You must add text to the required field");
    } else {
      grecaptcha.execute();
    }
  }

  function onload() {
    var element = document.getElementById('submit');
    element.onclick = validate;
  }
</script>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</head>
<body>
   <form>
     Name: (required) <input id="field" name="field">
     <div id='recaptcha' class="g-recaptcha"
          data-sitekey="your_site_key"
          data-callback="onSubmit"
          data-size="invisible"></div>
     <button id='submit'>submit</button>
   </form>
<script>onload();</script>
</body>
</html>