Vue reCAPTCHA v3 Integration

Common errors

• TypeError: app.component is not a function

  cause Attempting to use `vue-recaptcha-v3` v2.x (Vue 3 compatible) with a Vue 2 application setup (e.g., `import Vue from 'vue'; Vue.use(...)`).
  fix For Vue 2 applications, downgrade `vue-recaptcha-v3` to a `^1.9.0` version. For Vue 3, ensure your application setup uses `createApp()` and the correct import for `VueReCaptcha`.

• Uncaught (in promise) Error: reCAPTCHA v3 site key not found

  cause The `siteKey` option was either not provided or was an empty string during the plugin installation.
  fix Ensure you pass a valid Google reCAPTCHA v3 site key to the `Vue.use(VueReCaptcha, { siteKey: 'YOUR_SITE_KEY' })` configuration object.

• Property '$recaptcha' does not exist on type 'ComponentPublicInstance<...>'

  cause Using Vue 3 Options API with TypeScript without extending the Vue instance's type definitions for `$recaptcha` and related properties.
  fix Create a `shims-vue-recaptcha-v3.d.ts` file in your project with the provided type declarations from the package documentation to augment `ComponentCustomProperties`.

Warnings

• breaking Version 2.0.0 of `vue-recaptcha-v3` introduces full support for Vue 3 and is not backward compatible with Vue 2 applications. Attempting to use v2.x with Vue 2 will result in runtime errors.
  Fix: For Vue 2 applications, use `vue-recaptcha-v3` version `^1.9.0`. For Vue 3, ensure you are on `^2.0.0` or later. Adjust your `package.json` accordingly and reinstall dependencies.
• gotcha reCAPTCHA v3 requires a valid site key obtained from the Google reCAPTCHA admin console for your specific domain. Using an invalid or incorrect key will prevent reCAPTCHA from loading or executing correctly, leading to failed token generation.
  Fix: Register your domain on the Google reCAPTCHA admin console to obtain a site key. Ensure the site key passed to `Vue.use(VueReCaptcha, { siteKey: '...' })` matches the one configured for your domain.
• gotcha When using TypeScript with the Vue 3 Options API, instance properties like `$recaptcha`, `$recaptchaLoaded`, and `$recaptchaInstance` will not have type suggestions or checks by default.
  Fix: Create a `shims-vue-recaptcha-v3.d.ts` file and extend `ComponentCustomProperties` from `@vue/runtime-core` as described in the package's documentation to provide proper type inference.
• gotcha The `useReCaptcha` composition function provides `executeRecaptcha` and `recaptchaLoaded`. Earlier versions of the documentation (and potentially common user typos) might refer to `useRecaptcha` or `executeRecaptcha` as `executeRecaptcha` (lowercase 'c').
  Fix: Always use the correct capitalization: `useReCaptcha` for the hook, and `executeRecaptcha` for the function returned by the hook. Refer to the latest package documentation for accurate symbol names.

Install

• npm install vue-recaptcha-v3 npm
• yarn add vue-recaptcha-v3 yarn
• pnpm add vue-recaptcha-v3 pnpm

Imports

• VueReCaptcha
  wrong:

  const { VueReCaptcha } = require('vue-recaptcha-v3')

  correct:

  import { VueReCaptcha } from 'vue-recaptcha-v3'

  This is the primary named export for installing the plugin globally in Vue applications. CommonJS `require` is not officially supported for modern Vue 3 applications.
• useReCaptcha
  wrong:

  import { useRecaptcha } from 'vue-recaptcha-v3'

  correct:

  import { useReCaptcha } from 'vue-recaptcha-v3'

  Used with Vue 3's Composition API. Note the correct capitalization: `useReCaptcha`, not `useRecaptcha` as was a typo in earlier documentation.
• ComponentCustomProperties
  wrong:

  declare module 'vue' { interface Vue { $recaptcha: (action: string) => Promise<string> } }

  correct:

  declare module '@vue/runtime-core' { interface ComponentCustomProperties { $recaptcha: (action: string) => Promise<string> } }

  For TypeScript users in Vue 3 Options API, extending `ComponentCustomProperties` from `@vue/runtime-core` is necessary for type inference of instance properties like `$recaptcha` and `$recaptchaLoaded`.

Quickstart

This quickstart demonstrates how to initialize the `vue-recaptcha-v3` plugin for Vue 3 using the Composition API, execute a reCAPTCHA action, and retrieve the token. It includes an optional environment variable for the site key and shows basic console logging of the token.

import { createApp } from 'vue'
import { VueReCaptcha, useReCaptcha } from 'vue-recaptcha-v3'

const VUE_APP_RECAPTCHA_SITE_KEY = process.env.VUE_APP_RECAPTCHA_SITE_KEY ?? 'YOUR_SITE_KEY_HERE';

const App = {
  setup() {
    const { executeRecaptcha, recaptchaLoaded } = useReCaptcha()

    const handleRecaptcha = async () => {
      console.log('Executing reCAPTCHA...')
      // (optional) Wait until recaptcha has been loaded.
      await recaptchaLoaded()

      // Execute reCAPTCHA with a specific action.
      const token = await executeRecaptcha('submit_form')

      console.log('reCAPTCHA token:', token)
      // In a real application, you would send this token to your backend for verification.
      alert(`reCAPTCHA token: ${token}\n(Check console for more details)`) 
    }

    return {
      handleRecaptcha
    }
  },
  template: `
    <div>
      <h1>Vue reCAPTCHA v3 Quickstart</h1>
      <p>Click the button below to execute a reCAPTCHA v3 action and get a token.</p>
      <button @click="handleRecaptcha">Execute reCAPTCHA</button>
      <p>Note: The reCAPTCHA badge might be hidden if 'useRecaptchaNet' is enabled or via instance methods.</p>
    </div>
  `
}

createApp(App)
  .use(VueReCaptcha, { siteKey: VUE_APP_RECAPTCHA_SITE_KEY, loaderOptions: { useRecaptchaNet: true }})
  .mount('#app')