Vue reCAPTCHA Component

Common errors

• [Vue warn]: Failed to resolve component: VueRecaptcha

  cause The VueRecaptcha component was not correctly imported or registered with your Vue application.
  fix Ensure you are using `import { VueRecaptcha } from 'vue-recaptcha'` and then registering it, e.g., `app.component('VueRecaptcha', VueRecaptcha)` or including it in your component's `components` option.

• TypeError: VueRecaptcha is not a constructor (or is not a function)

  cause This error often indicates an incorrect import style, attempting to use a named export as a default export or vice-versa.
  fix Since v2.0.0, `VueRecaptcha` is a named export. Use `import { VueRecaptcha } from 'vue-recaptcha'`.

• ReferenceError: grecaptcha is not defined

  cause The Google reCAPTCHA script (`https://www.google.com/recaptcha/api.js`) has not been loaded or is not available on the global `window` object when the component attempts to render.
  fix Ensure `:loadRecaptchaScript="true"` is set on the `VueRecaptcha` component, or manually load the script by including `<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>` in your `index.html` (if `loadRecaptchaScript` is `false`).

Warnings

• breaking VueRecaptcha changed from a default export to a named export.
  Fix: Change your import statement from `import VueRecaptcha from 'vue-recaptcha'` to `import { VueRecaptcha } from 'vue-recaptcha'`.
• breaking For Vue 2 compatibility with vue-recaptcha v2.x, the `@vue/composition-api` package is now a required peer dependency.
  Fix: Install the composition API package: `npm install @vue/composition-api` or `yarn add @vue/composition-api`.
• breaking The `loadRecaptchaScript` prop now defaults to `true`, meaning the component will automatically inject the reCAPTCHA script into your page. Previously, it defaulted to `false`.
  Fix: If you are manually loading the reCAPTCHA script, you should explicitly set `:loadRecaptchaScript="false"` on the component to prevent duplicate script loading.
• gotcha Version 2.0.2 of the package had publishing issues and did not correctly update. It is recommended to skip this version.
  Fix: If you are on 2.0.2, upgrade directly to 2.0.3 or a later stable version to ensure all bug fixes are applied correctly.

Install

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

Imports

• VueRecaptcha
  wrong:

  import VueRecaptcha from 'vue-recaptcha'

  correct:

  import { VueRecaptcha } from 'vue-recaptcha'

  Since v2.0.0, VueRecaptcha is a named export. Older versions used a default export.
• VueRecaptcha
  wrong:

  const { VueRecaptcha } = require('vue-recaptcha')

  correct:

  import { VueRecaptcha } from 'vue-recaptcha'

  The library is primarily designed for ES Modules. While CommonJS might work with transpilers, named ESM imports are the canonical approach.
• VueRecaptchaProps

  import type { VueRecaptchaProps } from 'vue-recaptcha'

  Type import for component props, useful for TypeScript projects.

Quickstart

This quickstart demonstrates a basic Vue 3 application using the VueRecaptcha component. It shows how to import and register the component, pass a site key, automatically load the reCAPTCHA script, and handle verification, expiration, and error events to display the reCAPTCHA token or messages.

import { createApp } from 'vue';
import { VueRecaptcha } from 'vue-recaptcha';

const app = createApp({
  data() {
    return {
      sitekey: process.env.VUE_APP_RECAPTCHA_SITE_KEY ?? '',
      token: '',
      error: ''
    };
  },
  methods: {
    onVerify(response) {
      this.token = response;
      this.error = '';
      console.log('reCAPTCHA token:', response);
      // Send token to your backend for verification
    },
    onExpired() {
      this.token = '';
      console.log('reCAPTCHA token expired.');
    },
    onError(error) {
      this.error = error;
      this.token = '';
      console.error('reCAPTCHA error:', error);
    }
  },
  template: `
    <div>
      <h1>reCAPTCHA Example</h1>
      <VueRecaptcha
        :sitekey="sitekey"
        :loadRecaptchaScript="true"
        @verify="onVerify"
        @expired="onExpired"
        @error="onError"
      ></VueRecaptcha>
      <p v-if="token">Token: {{ token }}</p>
      <p v-if="error" style="color: red;">Error: {{ error }}</p>
      <p v-else-if="!token && sitekey">Waiting for reCAPTCHA verification...</p>
      <p v-else>Please set VUE_APP_RECAPTCHA_SITE_KEY environment variable.</p>
    </div>
  `
});

app.component('VueRecaptcha', VueRecaptcha);
app.mount('#app');