# Invisible reCAPTCHA

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

To invoke the invisible reCAPTCHA, you can either:

- [Automatically bind the challenge to a button](https://developers.google.com/recaptcha/docs/invisible#auto_render) or
- [Programmatically bind the challenge to a button](https://developers.google.com/recaptcha/docs/invisible#explicit_render) or
- [Programmatically invoke the challenge](https://developers.google.com/recaptcha/docs/invisible#programmatic_execute)

See [Configurations](https://developers.google.com/recaptcha/docs/invisible#config) 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](https://developers.google.com/recaptcha/docs/verify) 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.](https://developers.google.com/recaptcha/docs/display#explicit_render)

## 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](https://developers.google.com/recaptcha/docs/invisible#js_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](https://developers.google.com/recaptcha/docs/language) | 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' lets you position it with CSS. |
| `data-size` | size | invisible |   | Optional. Used to create an invisible widget bound to a div and programmatically 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 |   |   | 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 |   |   | 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 |   |   | Optional. The name of your callback function, executed when reCAPTCHA encounters an error (usually network connectivity) and cannot continue until connectivity is restored. If you specify a function here, you are responsible for informing the user that they should retry. |
|   | isolated |   | false | Optional. For plugin owners to not interfere with existing reCAPTCHA installations on a page. If true, this reCAPTCHA instance will be part of a separate ID space. |

## 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](https://developers.google.com/recaptcha/docs/invisible#render_param). **inherit** Use existing data-\* attributes on the element if the corresponding parameter is not specified. The parameters will take precedence over the attributes. |
| `grecaptcha.execute( opt_widget_id )` | Programmatically 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>
            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>